# Access and permissions

Source: https://hygraph.com/docs/getting-started/access-and-permissions/access-and-permissions-overview

Every user and API client in Hygraph is assigned a set of permissions that controls what they can read, write, and configure. This section covers how to set that up, whether you are onboarding a team member, creating a custom role, or securing an API integration.

Hygraph uses three mechanisms to grant permissions:

- **Roles** control what authenticated users can do in the project.
- **Permanent Auth Tokens (PATs)** control what API clients can do. 
- **Content API permissions** control what unauthenticated requests to the public Content API can read.

All three use the same permission types: content permissions (read, create, update, delete, publish, unpublish) and Management API permissions (schema, environments, settings). Content permissions are environment-specific. Management API permissions apply across all environments in the project.

When setting up access for your project, work through these decisions in order:

1. **Who needs access?** Identify everyone who needs access to your project. For each person or system, determine whether they should be granted access through a role, a PAT, or the public Content API settings.
2. **What can they do?** Define the content permissions (which models, locales, and content stages) and any Management API permissions relevant to their role or token.
3. **On which environments?** Content permissions are environment-specific, so you configure them separately per environment. Management API permissions apply globally across all environments in the project.

## Who is this section for?

- Project admins managing users and environments
- Developers securing API access for applications

### Manage your team

- [Manage team members](/docs/getting-started/access-and-permissions/manage-team-members): Invite collaborators to your project, assign roles, and manage access as your team grows.
- [User roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions): Understand system roles, create custom roles, and define what users can read, write, publish, or manage.

### Configure API access

- [API access](/docs/getting-started/access-and-permissions/api-access): Configure public Content API access, create Permanent Auth Tokens (PATs), and authenticate API requests.
- [Content API permissions](/docs/getting-started/access-and-permissions/content-api-permissions): Reference for content permission rules, including model-level, locale, and content stage configuration.
- [Management API permissions](/docs/getting-started/access-and-permissions/management-api-permissions): Reference for permissions that control UI visibility for roles and programmatic access for PATs across schema, environments, and project settings.

---
# API access

Source: https://hygraph.com/docs/getting-started/access-and-permissions/api-access

The **API Access** section of your project settings is where you find your API endpoints, configure unauthenticated Content API permissions, and manage Permanent Auth Tokens (PATs). Navigate to **Project Settings > Access** to get started.

<Alert theme="info">
For a conceptual overview of authorization and authentication in Hygraph, see [Authorization](/docs/api-reference/basics/authorization).
</Alert>

## Endpoints

The **Endpoints** section lists the API URLs for your project's environments. Click any URL to copy it to your clipboard.

| Endpoint                                                                                     | Description                                                                                                                                                                                                                                                                                          |
|----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| High Performance Content API | Low-latency, high-read-throughput endpoint for content delivery.                                                                                                                                                                                                                                     |
| MCP Server API                                                                               | Enables structured communication between AI assistants and Hygraph via the Model Context Protocol. See [setting up Hygraph's MCP server](/docs/hygraph-ai/mcp-server).                                                                                                                               |
| Management API                                                                               | Handles all structural elements of a project. Use it via the [Management SDK](/docs/api-reference/management-sdk/management-sdk).                                                                                                                                                                    |

## Content API

The **Content API** section lets you configure access permissions for unauthenticated requests to your project's Content API, that is, requests made without a PAT.

![API Access - Content API](/images/docs/user-guides/api-access/api-access-publicapi.png)

### Default stage for public content delivery

This setting determines which content stage is served when no stage parameter is included in a query or HTTP header. To change it:

1. Click **Change default stage** next to the current stage tag.
2. Select a stage from the available options.
3. Click **Change** to save.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xad3hu7m07vx5bpdzpmt" caption="API Access - Default stage for public content delivery" />

[Learn more about the default public stage](/docs/api-reference/basics/authorization#default-public-stage).

### Content permissions

Content permissions determine what unauthenticated users can read from your Content API. This section lets you view, add, edit, and delete permissions.

![API Access - Content permissions](/images/docs/user-guides/api-access/content-permissions.png)

For a full explanation of how content permissions work, see [Content permissions](/docs/getting-started/access-and-permissions/content-api-permissions).

#### Add a permission

Click **+ Add permission** at the top right of the permissions table, then follow the [Add content permissions flow](/docs/getting-started/access-and-permissions/user-roles-and-permissions#configure-content-permissions).

#### Edit a permission

Click the context menu to the left of a permission row and select **Edit**. A dialog will appear where you can update the locale or stage.

![API Access - Edit permissions](/images/docs/user-guides/api-access/edit-permissions.png)

#### Delete a permission

Click the context menu to the left of a permission row and select **Delete**. Confirm the deletion in the dialog that appears. This action is permanent and cannot be undone.

![API Access - Delete permissions](/images/docs/user-guides/api-access/delete-permissions.png)

## Permanent Auth Tokens

Permanent Auth Tokens (PATs) provide authenticated access to the Content API and Management API using Bearer token authentication. Each token can be configured with its own set of content and Management API permissions.

The tokens table lists all existing tokens for the project. Click the copy icon to the right of a token to copy it to your clipboard.

See [Authorization — Permanent auth tokens](/docs/api-reference/basics/authorization#permanent-auth-tokens) for a conceptual overview of how PATs work.

![API Access - Permanent Auth Tokens](/images/docs/user-guides/api-access/api-access-pat.png)

### Add a token

1. Click **+ Add token** at the top of the tokens table.
2. Enter a name and optional description for the token.
3. Select a default stage for content delivery using the radio buttons.
4. Click **Add & configure permissions** to create the token.

The token details screen opens, where you configure content API access and Management API permissions.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xa7mjaus07w51bm23kiq" caption="API Access - Add Tokens" />

### Configure Content API permissions

When a PAT is created, default content permissions are enabled: **Read** access on all models for all locales with `PUBLISHED` as the default content stage.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xaf2hu7u07vx2xzkzr0m" caption="PAT - content permissions " />

From the token detail view you can:

- Change the default content delivery stage by clicking **Change default stage** and selecting a different option.
- Add a custom permission by clicking **+ Add permission** and following the [Add content permissions flow](/docs/getting-started/access-and-permissions/user-roles-and-permissions#configure-content-permissions).

### Configure Management API permissions

To configure Management API permissions for a token:

1. On the token details screen, scroll to the **Management API Permissions** section.
2. Click **Show all permissions** to view the full list. Only enabled permissions are shown by default.
3. Use the toggles to enable or disable individual permissions.
4. To bulk-enable or bulk-disable permissions, use the checkboxes to select multiple rows. The **Enable selected** or **Disable selected** action appears at the top of the table.

For a full reference of all available permissions, see [Management API permissions](/docs/getting-started/access-and-permissions/management-api-permissions).

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xah3javj07w5q7yu83z8" caption="Edit Management API permissions" />

### Edit a token

Click a token row in the table, or select **Edit** from its context menu. The token detail view will open, where you can update permissions as described above.

![API Access - Edit token](/images/docs/user-guides/api-access/edit-token.png)

### Delete a token

Select **Delete** from the token's context menu, or click **Delete** from within the token detail view. Confirm the deletion in the dialog that appears. Deleting a token is permanent and invalidates all JWTs (JSON Web Tokens) associated with it.

![API Access - Delete token](/images/docs/user-guides/api-access/delete-token.png)

### Can’t find your token in Hygraph?

If you copied a PAT a while ago and can’t find the same token string in Hygraph today, the token may still be active even if it looks different.

Hygraph uses JWTs (JSON Web Tokens) for Permanent Auth Tokens (PATs). In cases such as audience updates or issuer migrations, the encoded JWT string may change while still representing the same underlying token. Even after such changes, the token remains valid as long as the `jti` (JWT ID) claim within the token's payload remains unchanged. The `jti` claim serves as the authoritative identifier for the token.

To verify whether two tokens refer to the same underlying token, follow these steps:

1. Go to https://jwt.io and paste the token that you want to check. This token is no longer visible in Hygraph Studio.
2. Decode the token and locate the `jti` claim in the payload.
3. In Hygraph Studio, go to **Project settings > Access > Permanent Auth Tokens** and check the `jti` values for the tokens listed there.
4. Compare the `jti` values. If the `jti` value found in Step 2 matches the `jti` of a token available in Hygraph Studio, it is the same underlying Permanent Auth Token, even if the encoded JWT differs. The token is still active and has not been revoked. You can then decide whether to keep it or revoke it.
    - If you want to keep the token, you can replace the deleted JWT with the one that matches from Hygraph Studio.
    - If you want to revoke the token, you can delete it from Hygraph Studio. This action invalidates all JWTs associated with that token, including any previously issued ones.

![Permanent Auth Tokens list](/images/docs/user-guides/api-access/api-access-tokens.png)

## What's next

- [Content permissions](/docs/getting-started/access-and-permissions/content-api-permissions): How content permissions work and their limits.
- [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions): Create and configure roles, assign permissions, and set up role-based access.
- [Authorization](/docs/api-reference/basics/authorization): Public API permissions, PATs, and endpoints.

---
# Content API permissions

Source: https://hygraph.com/docs/getting-started/access-and-permissions/content-api-permissions

Content permissions control who can read, create, update, delete, publish, and unpublish content in your Hygraph project. You can configure permissions for unauthenticated Public API access, individual Permanent Auth Tokens (PATs), and custom roles.

Content permissions are environment-specific. Their configuration is applied per environment. If you are working with multiple environments, you must configure permissions separately for each one.

## Permission actions

The permission system is built on seven action types. Granting an action gives the Public API, a PAT, or a custom role permissions to perform that action on all models or a specific model.

| Action          | Description                               | Required permissions                                                       |
|-----------------|-------------------------------------------|----------------------------------------------------------------------------|
| `Read`          | Read content entries.                     | —                                                                          |
| `Read versions` | View version history for content entries. | —                                                                          |
| `Create`        | Create new content entries.               | `Read` on Draft stage and default locale, and `Create`                     |
| `Update`        | Modify existing content entries.          | `Read` on Draft stage, and `Update`                                        |
| `Delete`        | Delete content entries.                   | `Read` on all stages, `Delete`, and `Unpublish` on all stages except Draft |
| `Publish`       | Publish content entries.                  | `Read` on Draft stage, and `Publish` on Draft and target stage             |
| `Unpublish`     | Unpublish content entries.                | `Read` on all stages, and `Unpublish` on source stage                      |

<Alert theme="info">
The **Read versions** action grants access to the version history for a given entry. Custom roles that interact with content via the UI typically need this permission, since versioning is shown as part of the content editor form.
</Alert>

## Set up Public API access

The Public API is read-only. To expose content publicly via the API:

1. Navigate to **Project Settings > Access > Content API**.
2. In the **Content Permissions** box, click **Initialize defaults**. This sets `Read` permissions on all models for the **PUBLISHED** stage.
3. If you need custom rules instead, click **+ Add permission**, select **All models**, check **Read**, leave **Locales** and **Stages** at their defaults, and click **Create**.

The Public API is now accessible with read permissions.

![Public API Read Permissions](/images/docs/api-reference/basics/public-api-read.png)

[Learn more about working with the Public API](/docs/api-reference/basics/authorization).

## Set up a PAT with model-specific permissions

A [Permanent Auth Token (PAT)](/docs/api-reference/basics/authorization#permanent-auth-tokens) can be scoped to specific models and actions. The example below configures a PAT that can read, create, and update entries in a `Post` model only.

1. Navigate to **Project Settings > Access > Permanent Auth Tokens** and click **+ Add Token**.
2. Enter a token name and optional description, then click **Add & configure permissions**.
3. Under **Content API** in the token detail view, click **Add permissions**.
4. Select the **Post** model and check **Read**, **Create**, and **Update**. Leave **Locales**, **Stages**, and **Condition** at their defaults, then click **Create**.

The token can now read, create, and update `Post` entries.

With this configuration, the token cannot access related models such as `Author`, `Asset`, or `SEO`. To connect posts to those models, add separate permissions for each.

![PAT Post Permissions](/images/docs/api-reference/basics/pat-post-permissions.png)

[Learn more about authenticating with a PAT](/docs/api-reference/basics/authorization).

## Use conditions

Conditions let you restrict a permission to a subset of content entries. This section covers the syntax and constraints for writing conditions. For a walkthrough of how to add a condition to a role in the Hygraph UI, see [Using conditions in role setup](/docs/getting-started/access-and-permissions/user-roles-and-permissions#using-conditions).

To define a condition, write a `where` clause in JSON and paste it into the **Condition** field when creating or editing a permission for a specific model.

Build and test your `where` clause in the API Playground before adding it as a condition.

The following examples show conditions applied to a `Post` model:

- Grant access only to posts tagged with specific values:

    ```json
    { "tags_contains_some": ["GraphQL", "SEO"] }
    ```

- Extend the above to also include posts with no tags:

    ```json
    { "OR": [{ "tags_contains_some": ["GraphQL", "SEO"] }, { "tags": null }] }
    ```

    ![PAT Post Tag Conditions](/images/docs/api-reference/basics/pat-post-tag-conditions.png)

- Restrict access to posts related to a specific author by ID:

    ```json
    { "author": { "id_in": ["ckadqgca800ix011230ailipe"] } }
    ```

    For this to work, the token or role also needs read access on the `Author` model. You can optionally restrict that access to a single document:
    
    ```json
    { "id": "ckadqgca800ix011230ailipe" }
    ```
    
    ![PAT Post Author Conditions](/images/docs/api-reference/basics/pat-post-author-conditions.png)

## Limits and considerations

#### Total permissions per environment

You can configure up to 50 content permissions in a project environment. You can distribute these across the Public API, PATs, and custom roles as needed. 

[Learn more about working with environments](/docs/api-reference/basics/environments).

#### User system model and user attribution

Depending on what you need to expose, you may need to include `Read` access to the `User` system model. This is especially important for custom roles that interact with the UI, as user attribution fields (`createdBy`, `updatedBy`, and `publishedBy`) will not display without the appropriate permissions. Missing these permissions can also cause `not allowed` errors when mutating content from the content editor.

See [System fields — User fields](/docs/api-reference/schema/system-fields#user-fields) for more detail.

#### Custom roles

Custom roles have no permissions by default. At a minimum, a custom role needs:

- **Read** access on the `User` system model (required for user attribution to work in the UI)
- **Read versions** (required for versioning to display correctly in the content editor)

#### Conditions

Conditions must be kept up to date manually. If a field referenced in a condition is renamed or removed, or a related model changes, the condition will no longer be valid. The same applies when conditions reference specific document IDs.

Conditions cannot be applied to localized fields and do not support `search` capabilities.

#### Relations

When permissions are set on a model that has relations, permissions may be required on both models. For example, in a schema with `Post` and `Author` models, updating a `Post` to connect it to an `Author` also requires update permissions on the `Author` model, since an author can reference many posts.

[Learn more about relations](/docs/api-reference/schema/field-types#reference).

#### Locales

Permissions support locale-specific configuration. To create or update a document with non-localized fields, the user or token must have access to the default locale.

## What's next

- [Authorization](/docs/api-reference/basics/authorization): Public API permissions, PATs, and endpoints.
- [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions): Create and configure roles, assign permissions, and set up role-based access.
- [API access](/docs/getting-started/access-and-permissions/api-access): Manage API endpoints, Permanent Auth Tokens, and Content API permissions.

---
# Manage team members

Source: https://hygraph.com/docs/getting-started/access-and-permissions/manage-team-members

The **Members** screen gives you an overview of everyone on your project team and the roles they are assigned to. From here you can invite new members, change role assignments, remove members, and navigate to role details.

To access this screen, navigate to **Project Settings > Team > Members**.

![Project team members](/images/docs/user-guides/project-guides/projectsettings-team-members.png)

## Invite team members

You must invite a user to the project before you can assign them to a role.

1. Click **Invite members** at the top right of the **Members** screen.
2. Enter the user's **Email address** and select their **Role** from the dropdown. The dropdown lists all roles currently configured in your project. [Learn more about roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions).
3. Click **+ Add to list** to add the user to the invite queue. Repeat for additional members if needed.
4. Click **Invite** to send the invitation.

![Add team members](/images/docs/user-guides/project-guides/projectsettings-team-members-add.png)

### Resending invitations

For accounts not yet registered in Hygraph, wait at least 15 minutes before resending an invitation to the same email address. You can resend to the same address a maximum of three times within a 24-hour period.

## Change a member's role

1. Navigate to **Project Settings > Team > Members** and locate the user in the list.
2. Open the context menu for that user and select **Change role**.
3. The role list for that member becomes editable. Select a role from the list to add it.
4. Click **Update** to save the changes.

![Remove a team member from a role](/images/docs/user-guides/roles-and-permissions/change-role.png)

## Remove a member's role

1. Navigate to **Project Settings > Team > Members** and locate the user in the list.
2. Open the context menu for that user and select **Change role**.
3. The role list for that member becomes editable. Click the **×** next to a role name to remove it.
4. Click **Update** to save the changes.

![Remove a team member from a role](/images/docs/user-guides/roles-and-permissions/remove-role.png)

## Remove a member from the project

1. Navigate to **Project Settings > Team > Members** and locate the user in the list.
2. Open the context menu for that user and select **Remove from project**.
3. Confirm the action in the dialog that appears.

This action is permanent and cannot be undone. The user will lose access to the project immediately.

![Remove team member from a project](/images/docs/user-guides/project-guides/team-member-remove-from-project.png)

## View role details

To view the permissions associated with a role that a member belongs to:

1. Open the context menu for the team member.
2. Select **View role**. If the member has multiple roles, select the specific role you want to inspect.

This takes you to the [Roles & Permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions) screen for that role, where you can see the list of assigned members and the content and Management API permissions configured for it.

![View role](/images/docs/user-guides/project-guides/team-member-view-role.png)

## What's next

- [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions): Create and configure roles, assign permissions, and set up role-based access.
- [API access](/docs/getting-started/access-and-permissions/api-access): Manage API endpoints, Permanent Auth Tokens, and Content API permissions.

---
# Management API permissions

Source: https://hygraph.com/docs/getting-started/access-and-permissions/management-api-permissions

Management API permissions control what users assigned to a role can see in the Hygraph UI, and what actions Permanent Auth Tokens (PATs) can perform through the Management API. The same set of permissions is available for both [custom roles](/docs/getting-started/access-and-permissions/user-roles-and-permissions) and [Permanent Auth Tokens (PATs)](/docs/getting-started/access-and-permissions/api-access#permanent-auth-tokens), but their defaults and behaviors differ.

There are two types of Management API permissions:

- **View permissions** control UI visibility. Granting or revoking these shows or hides buttons, tabs, and sections in the interface for users assigned to that role. For example, the `Create new entries` permission controls whether the **+ Add entry** button appears in the content editor. It does not grant the ability to create entries through the API.
- **Action permissions** control what can be done via the Management API, such as creating models, updating fields, or managing webhooks.

This distinction is especially important for PATs. Granting a UI-only permission to a token has no effect, since tokens do not interact with the UI. Content creation through the API requires the appropriate Content API permissions, not Management API permissions.

Management API permissions are **global**. They apply across all environments in a project.

## Roles vs PATs: a key distinction
 
Understanding how Management API permissions behave differently for roles and PATs will save you a lot of confusion when configuring access.

- **Roles** - Management API permissions primarily control **UI visibility**. Granting a permission shows a button, tab, or section to users assigned to that role. Revoking it hides it. If a user lacks a permission, the effect is visible in the interface. They may not see a button, get an error when accessing a restricted area, or in some cases be logged out.
    - Defaults cover the read permissions needed to navigate the Hygraph UI correctly. Anything beyond that must be added manually.
 
- **PATs** - Management API permissions control **API access**. If a token lacks a permission, the API call fails with an insufficient permissions error. There is no UI involved.
    - Defaults cover `create` and `read` permissions suited for programmatic API access.

This distinction matters because some permissions are **UI-only**. They control what users see in the Hygraph interface but have no effect on what a PAT can do programmatically. The most common example is **Create new entries**, which shows or hides the **+ Add entry** button in the content editor. Granting this to a PAT does nothing, because PATs do not interact with the UI and content creation is handled by the Content API, not the Management API.
 
<Alert theme="info">
Permissions marked as **UI-only** in the tables below have no effect on PAT behavior. For PATs, content operations such as creating, updating, publishing, and deleting entries should be configured under the token's [content API permissions](/docs/getting-started/access-and-permissions/api-access#configure-content-api-permissions).
</Alert>

## How they differ from content permissions

Content permissions govern access to your project's content entries (read, create, update, delete, publish, unpublish). Management API permissions govern access to your project's structural and configuration elements, such as schema, environments, roles, webhooks, and so on.

## Roles

<Alert theme="info">
Custom roles are an enterprise feature. <Link href="https://hygraph.com/contact" target="_blank">Contact the sales team to access them</Link>.
</Alert>

[Hygraph provides five system roles](/docs/getting-started/access-and-permissions/user-roles-and-permissions#system-roles), Owner, Admin, Developer, Editor, and Contributor, each with a predefined permission set that reflects its responsibilities. For example, an Editor cannot access the API Playground, while an Admin or Developer can.

Every custom role is assigned a set of default Management API permissions on creation. These defaults cover the minimum needed to use the Hygraph UI correctly. All additional permissions can be added manually depending on what the role needs to do.

Note that granting a role additional Management API permissions controls UI visibility only. If users also have Content API permissions granting a particular action, they can still perform that action via the API even if the corresponding UI button is hidden. You can grant a role full content permissions while using Management API permissions to hide specific actions in the UI. Users assigned that role can still perform those actions by calling the API directly.

**Content** and **Assets** tabs in Studio are governed by the following Management API permissions:
- **Content**: **Read public view groups** and **Read public content views** (not in defaults). Sidebar views also need **Read on DRAFT** per model via [content permissions](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions).
- **Assets**: **Read public view groups** and **Read public content views** + **Read** content permission on the **Asset** model. Assets does not appear without access to the **Content** tab.
- **Tables / entries**: Content permissions per model and stage.

### Roles - Project & Studio access

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Change the name, picture and description of a project | Allows users to edit project details and manage support access in **Project Settings > General > Project**. Without this permission, the section is visible but read-only and grayed out. Included by default for the **Admin** and **Developer** system roles. | No |
| Can use the playground | Without this permission, users cannot see the **API Playground** in the top-level menu, or the **Preview in playground** option in the content editor and Assets. | No |
| Read audit logs | Without this permission, users cannot see the **Audit logs** tab in **Project Settings**. | No |
| Can see Team Member Settings | Without this permission, the user cannot see the **Members** tab in **Project Settings > Team**. | No |
| Can see Role & Permissions Settings | Without this permission, the user cannot see the **Roles** menu in project settings. | No |
| Can see schema view | Allows the user to see the schema editor. Deselect to hide the schema view for roles where it is not relevant. | No |
| Can see project settings | Without this permission, users cannot see **Project Settings** in the Studio sidebar or open project settings screens. | Yes |
| Can see environment selector | Without this permission, users cannot see the environment selector in Studio. | Yes |

### Roles - Models, components, fields

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create new models | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot use the **+ Add** button to create new models. | Yes |
| Read existing models | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot see models in it. | Yes |
| Update existing models | Grants users the ability to edit the **Settings** tab of models. Users also need permission to read the schema and models. | No |
| Delete existing models | Without this permission, the user cannot see the **Delete** option for models. | No |
| Create new components | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot use the **+ Add** button to create new components. | Yes |
| Read existing components | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot see components in it. | Yes |
| Update existing components | Grants users the ability to edit the **Settings** tab of components in the schema editor. Requires **`Can see schema view`**, **Read existing components**, and other read access as needed. Controls schema-level component metadata only. | No |
| Delete existing components | Without this permission, the user cannot see the **Delete** option in a component's context menu. | No |
| Read existing fields | Without this permission, the user cannot see or access the **Fields** tab in the UI. | Yes |
| Create new fields | Without this permission, the user cannot see the **Fields** side panel in the schema editor. | Yes |
| Update existing fields | Allows users to see the **Edit** button on field cards in models and edit field details. Users must also have permission to read the schema and models. Without this permission, the **Edit field** button is hidden and the drag-and-drop anchor is not displayed. | No |
| Delete existing fields | Allows users to delete fields from a model in the schema editor. Users must also have permission to read the schema and models. | No |

### Roles - Enumerations

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Read existing enumerations | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot see enumerations in it. | Yes |
| Create new enumerations | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot use the **+ Add** button to create new enumerations. | Yes |
| Update existing enumerations | Grants users the ability to edit enumeration details. Users also need permission to read the schema and enumerations. | No |
| Delete existing enumerations | Without this permission, the **Delete** option is hidden in the enumeration details context menu. | No |

### Roles - Taxonomies

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Read taxonomy | With **`Can see schema view`**, required to open taxonomies and view taxonomy details (including the **Settings** tab). Without it, users cannot access taxonomy definition screens in the schema area. | Yes |
| Create taxonomy | Without this permission, users with **`Can see schema view`** cannot create new taxonomies. Opening existing taxonomies depends on **Read taxonomy** and schema access. Creating a taxonomy typically also requires **Create taxonomy node** for **+ Add** flows. | Yes |
| Update taxonomy | Without this permission, the taxonomy Settings page is read-only. | No |
| Delete taxonomy | Without this permission, the **Delete** option is hidden in the taxonomy details context menu. | No |
| Read taxonomy node | With **`Can see schema view`**, required to browse taxonomy **Nodes** and view node-related detail. Without it, exploring taxonomy nodes is not available. | Yes |
| Create taxonomy node | Allows users to use **+ Add child node** (or equivalent). Together with **Create taxonomy**, enables **+ Add** to create a taxonomy where the UI exposes it. | Yes |
| Update taxonomy node | Allows users to add new child nodes, rename nodes, or move nodes to a different parent. Without this permission, users can only view taxonomy node details. | No |
| Delete taxonomy node | Without this permission, the **Delete** option is hidden next to the taxonomy node. | No |

### Roles - Remote sources

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Read remote sources | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot see remote sources in it. | Yes |
| Create remote sources | Without this permission, a user with **`Can see schema view`** can access the schema editor but cannot use the **+ Add** flow to create new remote sources. | Yes |
| Update remote sources | Grants users the ability to edit the **Settings** tab of remote sources. Without this permission, the **Save** button is hidden on the remote source settings screen. | No |
| Delete remote sources | Without this permission, users cannot see the **Delete** option for remote sources. | No |

### Roles - Content views

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create public content views | Without this permission, the **Add custom view** button is hidden. | No |
| Read public content views | Required together with **Read public view groups** to access the **Content** tab in Studio. To see views listed in the sidebar, assign [Read content permissions on the DRAFT stage](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) on models. For **Assets**, also grant **Read** on the Asset model via [content permissions](/docs/getting-started/access-and-permissions/api-access#configure-content-api-permissions). | No |
| Update public content views | Without this permission, the user cannot see the **Edit custom view** option in the custom view context menu. | No |
| Update system content views | Without this permission, the user cannot see the **Update default view** option in the content editor and Assets. | No |
| Delete public content views | Without this permission, the **Delete custom view** option is hidden in the custom view context menu. | No |

### Roles - View groups

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create public view groups | Grants users the ability to create view groups. | No |
| Read public view groups | Required together with **Read public content views** to access the **Content** tab in Studio. To see views listed in the sidebar, assign [Read content permissions on the DRAFT stage](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) on models. For **Assets**, also grant **Read** on the Asset model via [content permissions](/docs/getting-started/access-and-permissions/api-access#configure-content-api-permissions). | No |
| Update public view groups | Without this permission, view groups cannot be updated. | No |
| Delete public view groups | Without this permission, users will be logged out when attempting to delete a public view group. | No |

### Roles - Locales & stages

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Read locales | Without this permission, users receive an error when trying to access locale information. | Yes |
| Create locales | Without this permission, users cannot use the **Add** button in **Project Settings > General > Locales**. | No |
| Update locales | Without this permission, locales in **Project Settings > General > Locales** are read-only and grayed out. | No |
| Delete locales | Without this permission, the **Delete** button is hidden in **Project Settings > General > Locales**. | No |
| Read stages | Required to access content stage information. | Yes |
| Create stages | Allows users to see the **+ Add stage** button in **Project Settings > General > Content Stages**. | No |
| Update stages | Without this permission, the user cannot see the **Content stages** option in project settings. | No |
| Delete stages | Without this permission, clicking **Delete** in **Project Settings > General > Content Stages** throws an error. | No |

### Roles - Environments

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Read existing environments | Without this permission, users cannot access the project and will receive an error when attempting to log in. | Yes |
| Create new environment | Without this permission, the **Clone** button in **Project Settings > General > Environments** is disabled. | No |
| Update an existing environment | Grants the ability to edit environments through the Management API and related Studio controls. | No |
| Delete an existing environment | Without this permission, the **Delete** option in **Project Settings > General > Environments** is disabled. | No |
| Promote an existing environment | Without this permission, the **Promote to master** button in **Project Settings > General > Environments** is disabled. | No |

### Roles - Environment backups

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create new environment backup | Allows creating a new environment backup. | No |
| Read existing environment backups and their details | Allows reading existing environment backups and their details. | No |
| Update an existing environment backup | Allows updating an existing environment backup. | No |
| Delete an existing environment backup | Allows deleting an existing environment backup. | No |
| Restore an existing environment backup to a standard environment | Allows restoring an existing environment backup to a standard environment. | No |

### Roles - Content freeze

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Allows starting, scheduling, and lifting content freezes | Without this permission, users cannot access **Project Settings > Governance > Content Freeze**, use the **Manage freeze** link in the Studio banner, or start, schedule, or lift content freezes. | No |

### Roles - Content permission administration

Management permissions that control whether a user can manage **content permission** rows in Settings (not document Read/Create itself).

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Can create content permissions | Without this permission, users cannot see the **Add permission** option in the Public Content API, roles, and PATs sections of project settings. | No |
| Can read content permissions | Without this permission, the user cannot see the **Content permissions** block for roles and PATs in project settings. | No |
| Can update content permissions | Without this permission, users cannot see the **Edit** option for content permissions in the Public Content API, roles, and PATs sections of project settings. | No |
| Can delete content permissions | Without this permission, users cannot see the **Delete** option for content permissions in the Public Content API, roles, and PATs sections of project settings. | No |

### Roles - Permanent auth tokens

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Can create new permanent auth tokens | Without this permission, the **+ Add Token** button is hidden on **Permanent Auth Tokens** in **Project Settings**. | No |
| Can read existing permanent auth tokens | Allows users to see the **Access** section in **Project Settings**. For the **API Playground**, grant with **`Can use the playground`**. | No |
| Can update existing permanent auth tokens | Without this permission, the **Edit** option is hidden in the PAT context menu in **Project Settings > Access**. | No |
| Can delete existing permanent auth tokens | Without this permission, the **Delete** option is hidden in the PAT context menu in **Project Settings > Access**. | No |

### Roles - Webhooks

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create new webhooks | Without this permission, the user cannot see the **+ Add webhook** button. | No |
| Read existing webhooks | Without this permission, the user cannot see the **Webhooks** tab in the main navigation. | No |
| Update existing webhooks | Without this permission, the user cannot see the **Edit** button for webhooks. | No |
| Delete an existing webhook | Without this permission, the user cannot see the **Delete** option for webhooks. | No |

### Roles - Workflows

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Read workflow | Required to access workflow information through the Management API and workflow-related UI context. | Yes |
| Create a new workflow | Allows creating a new workflow. | No |
| Update a workflow | Allows updating an existing workflow. | No |
| Delete a workflow | Allows deleting an existing workflow. | No |
| Create a new workflow step | Allows creating a new workflow step. | No |
| Update a workflow step | Allows updating an existing workflow step. | No |
| Delete a workflow step | Allows deleting an existing workflow step. | No |

### Roles - Users & team

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Invite a user into an existing project | Without this permission, the user cannot see the **Invite members** button in **Project Settings > Team > Members**. | No |
| Assign a role to a user | Without this permission, the user cannot see the **Assign role** option in **Project Settings > Team > Members**. | No |
| Remove a user from an existing project | Grants users the ability to see the **Remove** option for users. Also required to delete agents via **AI Hub → Agents**. | No |

### Roles - User roles

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create new roles | Without this permission, the user cannot see the option to add a custom role in the UI. | No |
| Update existing roles | Without this permission, the user can open all existing roles, but all update-related buttons are hidden and they will receive an error when attempting to edit content permissions. | No |
| Delete an existing role | Without this permission, the user cannot see the **Delete** option for custom roles. | No |

### Roles - Experimental, AI, usage

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Allows managing experimental features and their role assignments | Allows managing experimental features. | No |
| Create AI guidelines | Allows creating a new AI guideline. | No |
| Read AI guidelines | Allows reading existing AI guidelines. | No |
| Update AI guidelines | Allows updating an existing AI guideline. | No |
| Delete AI guidelines | Allows deleting an existing AI guideline. | No |
| Read observability data | Allows reading observability data. | No |

### Roles - Agents

<Alert theme="info">
**Invite a new agent**, **Remove an agent**, and **Delete an agent config** appear in Roles & Permissions but have no effect today. You can leave them disabled.

To delete an agent, use Delete on the agent card in **AI Hub → Agents**. This requires the [**Remove a user from an existing project**](#roles-users-and-team) permission.
</Alert>

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Create a new agent config | Without this permission, users cannot use **+ Add agent** in **AI Hub → Agents**. | No |
| Read agent config | Without this permission, users cannot open **AI Hub → Agents** or agent KPIs when the agents feature is enabled. | No |
| Update an agent config | Without this permission, users cannot edit or enable/disable agents in **AI Hub → Agents**. | No |
| Trigger an agent run | Without this permission, users cannot manually trigger agents from the content editor or content table. Does not apply to PATs or workflow-triggered runs. | No |

### Roles - Integrations & extensions

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Can add new integrations to an existing project | Allows creating a new integration. | No |
| Can see existing integrations in an existing project | Allows reading existing integrations. | No |
| Can update existing integrations in an existing project | Allows updating an existing integration. | No |
| Can delete existing integrations in an existing project | Allows deleting an existing integration. | No |
| Can trigger a netlify build for an existing integration | Allows triggering a build for a Netlify integration. | No |
| Can add new extension to an existing project | Allows creating a new extension. | No |
| Can see existing extensions in an existing project | Allows reading existing extensions. | No |
| Can update existing extensions in an existing project | Allows updating an existing extension. | No |
| Can delete existing extensions in an existing project | Allows deleting an existing extension. | No |

### Roles - App installations

| Permission name | Role description | Custom role default |
|-----------------|------------------|------------------------|
| Can add app installations | Without this permission, the **Explore apps** banner is hidden in the **Apps** section. Projects where this permission is not granted do not appear in the project selector dropdown for new app installations. | No |
| Can update app installations | Grants the ability to see the **Edit** button on app cards. | No |
| Can delete app installations | Without this permission, the user cannot see the **Uninstall** option in the app card context menu. | No |

### Roles - Legacy Management API content permissions

| Permission name | Role description | Alternative |
|-----------------|------------------|---------------|
| Read existing entries | Deprecated. **Does not** control **Content** / **Assets** tabs. | **Read public view groups** + **Read public content views**; **Assets** needs Asset model **Read** via [content permissions](/docs/getting-started/access-and-permissions/api-access#configure-content-api-permissions). |
| Create new entries | Affects **+ Add entry** in Studio. Does not replace Content API **Create**. | [Content API permissions — Create](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Delete existing entries | **Delete** button visibility in Studio. | [Content API permissions — Delete](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Publish non-published entries | Publish from draft where Studio checks this flag. | [Content API permissions — Publish](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Update existing non published entries | **Save** on draft / non-published where wired. | [Content API permissions — Update](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Update published entries | **Save** when published; unpublish where wired. | [Content API permissions — Update or Unpublish](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |

## Permanent Auth Tokens
 
PATs interact with the Management API programmatically. When you initialize default permissions for a new PAT, those defaults cover the common schema read and create operations needed to work with the [Management SDK](/docs/api-reference/management-sdk/management-sdk). If you need to update or delete schema elements, add those permissions manually.

<Alert theme="info">
**UI-only permissions have no effect on PATs.** Tokens do not interact with the Hygraph interface, so granting a UI-only permission to a token changes nothing. Content creation through the API requires the appropriate Content API permissions, not Management API permissions. If you need a token to create content, configure the appropriate [content API permissions](/docs/getting-started/access-and-permissions/api-access#configure-content-api-permissions) instead.
</Alert>

### PATs - Project & studio access

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Change the name, picture and description of a project | `PROJECT_UPDATE` | Required for project metadata mutations (name, picture, description, support access). | No |
| Can use the playground | `PLAYGROUND_USE` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. | No |
| Read audit logs | `AUDIT_LOGS_READ` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. | No |
| Can see Team Member Settings | `VIEW_TEAM_MEMBER_SETTINGS` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. | No |
| Can see Role & Permissions Settings | `VIEW_ROLE_PERMISSION_SETTINGS` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. | No |
| Can see schema view | `VIEW_SCHEMA` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. | No |
| Can see project settings | `VIEW_PROJECT_SETTINGS` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. Included in PAT **Initialize defaults**. | Yes |
| Can see environment selector | `VIEW_ENVIRONMENT_SELECTOR` | Studio-only for members with a role; not used to authorize typical PAT Management API traffic. | No |

### PATs - Models, components, fields

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create new models | `MODEL_CREATE` | Required for model-creation mutations (for example `createModel`, `createSimpleModel`). | Yes |
| Read existing models | `MODEL_READ` | Required to read models and for most schema mutations that reference existing models. | Yes |
| Update existing models | `MODEL_UPDATE` | Required for model update mutations. | No |
| Delete existing models | `MODEL_DELETE` | Required for model deletion mutations. | No |
| Create new components | `COMPONENT_CREATE` | Required for component-creation mutations. | Yes |
| Read existing components | `COMPONENT_READ` | Required to read components and for component-related schema operations. | Yes |
| Update existing components | `COMPONENT_UPDATE` | Required for component update mutations (schema components, not content entries). | No |
| Delete existing components | `COMPONENT_DELETE` | Required for component deletion mutations. | No |
| Read existing fields | `FIELD_READ` | Required to read fields and for field-related schema operations. | Yes |
| Create new fields | `FIELD_CREATE` | Required for field-creation mutations on models and components. | Yes |
| Update existing fields | `FIELD_UPDATE` | Required for field update mutations. | No |
| Delete existing fields | `FIELD_DELETE` | Required for field deletion mutations. | No |

### PATs - Enumerations

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Read existing enumerations | `ENUMERATION_READ` | Required to read enumerations and for enumeration-related schema operations. | Yes |
| Create new enumerations | `ENUMERATION_CREATE` | Required for enumeration-creation mutations. | Yes |
| Update existing enumerations | `ENUMERATION_UPDATE` | Required for enumeration update mutations. | No |
| Delete existing enumerations | `ENUMERATION_DELETE` | Required for enumeration deletion mutations. | No |

### PATs - Taxonomies

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Read taxonomy | `TAXONOMY_READ` | Required for taxonomy queries and taxonomy-related mutations. Not included in PAT **Initialize defaults**. | No |
| Create taxonomy | `TAXONOMY_CREATE` | Required for taxonomy creation mutations. | No |
| Update taxonomy | `TAXONOMY_UPDATE` | Required for taxonomy update mutations. | No |
| Delete taxonomy | `TAXONOMY_DELETE` | Required for taxonomy deletion mutations. | No |
| Read taxonomy node | `TAXONOMY_NODE_READ` | Required for taxonomy node queries and node-related mutations. | No |
| Create taxonomy node | `TAXONOMY_NODE_CREATE` | Required for taxonomy node creation mutations. | No |
| Update taxonomy node | `TAXONOMY_NODE_UPDATE` | Required for taxonomy node update mutations. | No |
| Delete taxonomy node | `TAXONOMY_NODE_DELETE` | Required for taxonomy node deletion mutations. | No |

### PATs - Remote sources

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Read remote sources | `REMOTE_SOURCE_READ` | Required to read remote sources and for remote-source-related schema operations. | Yes |
| Create remote sources | `REMOTE_SOURCE_CREATE` | Required for remote-source-creation mutations. | Yes |
| Update remote sources | `REMOTE_SOURCE_UPDATE` | Required for remote source update mutations. | No |
| Delete remote sources | `REMOTE_SOURCE_DELETE` | Required for remote source deletion mutations. | No |

### PATs - Content views

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create public content views | `CONTENTVIEW_CREATE` | Required for custom content-view creation mutations. | No |
| Read public content views | `CONTENTVIEW_READ` | Required to read content views (`environment.contentView`, `environment.contentViews`). | No |
| Update public content views | `CONTENTVIEW_UPDATE` | Required to update **custom** content views. | No |
| Update system content views | `CONTENTVIEW_SYSTEM_UPDATE` | Required to update **system / default** content views. | No |
| Delete public content views | `CONTENTVIEW_DELETE` | Required to delete **custom** content views. | No |

### PATs - View groups

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create public view groups | `VIEW_GROUP_CREATE` | Required for view-group creation mutations. | No |
| Read public view groups | `VIEW_GROUP_READ` | Required to read view groups (`environment.viewGroups` and related fields). | No |
| Update public view groups | `VIEW_GROUP_UPDATE` | Required for view-group update mutations. | No |
| Delete public view groups | `VIEW_GROUP_DELETE` | Required for view-group deletion mutations. | No |

### PATs - Locales & stages

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Read locales | `LOCALE_READ` | Required for locale queries and locale-dependent Management API operations. | Yes |
| Create locales | `LOCALE_CREATE` | Required for locale creation mutations. | No |
| Update locales | `LOCALE_UPDATE` | Required for locale update mutations. | No |
| Delete locales | `LOCALE_DELETE` | Required for locale deletion mutations. | No |
| Read stages | `STAGE_READ` | Required for stage queries and content-stage configuration via the Management API. | Yes |
| Create stages | `STAGE_CREATE` | Required for content-stage creation mutations. | No |
| Update stages | `STAGE_UPDATE` | Required for content-stage update mutations. | No |
| Delete stages | `STAGE_DELETE` | Required for content-stage deletion mutations. | No |

### PATs - Environments

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Read existing environments | `ENVIRONMENT_READ` | Required for environment-scoped queries and mutations for the PAT's environment. | Yes |
| Create new environment | `ENVIRONMENT_CREATE` | Required for environment clone/create mutations. | No |
| Update an existing environment | `ENVIRONMENT_UPDATE` | Required for environment update mutations. | No |
| Delete an existing environment | `ENVIRONMENT_DELETE` | Required for environment deletion mutations. | No |
| Promote an existing environment | `ENVIRONMENT_PROMOTE` | Required for promote-to-master (and similar promote) mutations. Restoring from backup uses `ENVIRONMENT_BACKUP_RESTORE`, not this action. | No |

### PATs - Environment backups

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create new environment backup | `ENVIRONMENT_BACKUP_CREATE` | Required for environment backup creation mutations. | No |
| Read existing environment backups and their details | `ENVIRONMENT_BACKUP_READ` | Required to query environment backups and their metadata. | No |
| Update an existing environment backup | `ENVIRONMENT_BACKUP_UPDATE` | Required for environment backup update mutations. | No |
| Delete an existing environment backup | `ENVIRONMENT_BACKUP_DELETE` | Required for environment backup deletion mutations. | No |
| Restore an existing environment backup to a standard environment | `ENVIRONMENT_BACKUP_RESTORE` | Required to restore a backup into a standard environment. | No |

### PATs - Content freeze

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Allows starting, scheduling, and lifting content freezes | `MANAGE_CONTENT_FREEZE` | Required for `startContentFreeze` and `liftContentFreeze` mutations. | No |

### PATs - Content permission administration

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Can create content permissions | `CONTENT_PERMISSION_CREATE` | Required to create content-permission rows (roles, PATs, or public Content API target) via the Management API. | No |
| Can read content permissions | `CONTENT_PERMISSION_READ` | Required to read content-permission configuration via the Management API. | No |
| Can update content permissions | `CONTENT_PERMISSION_UPDATE` | Required to update content-permission rows via the Management API. | No |
| Can delete content permissions | `CONTENT_PERMISSION_DELETE` | Required to delete content-permission rows via the Management API. | No |

### PATs - Permanent auth tokens

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Can create new permanent auth tokens | `PAT_CREATE` | Required for PAT creation mutations. Usually granted on a **custom role** for admins; grant on a PAT only when automation manages other PATs. | No |
| Can read existing permanent auth tokens | `PAT_READ` | Required for PAT read/list operations. Usually granted on a **custom role** for admins. | No |
| Can update existing permanent auth tokens | `PAT_UPDATE` | Required for PAT update mutations. Usually granted on a **custom role** for admins. | No |
| Can delete existing permanent auth tokens | `PAT_DELETE` | Required for PAT deletion mutations. Usually granted on a **custom role** for admins. | No |

### PATs - Webhooks

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create new webhooks | `WEBHOOK_CREATE` | Required for webhook creation mutations. | No |
| Read existing webhooks | `WEBHOOK_READ` | Required for webhook queries. Studio navigation is controlled by custom roles. | No |
| Update existing webhooks | `WEBHOOK_UPDATE` | Required for webhook update mutations. | No |
| Delete an existing webhook | `WEBHOOK_DELETE` | Required for webhook deletion mutations. | No |

### PATs - Workflows

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Read workflow | `WORKFLOW_READ` | Required for workflow queries and workflow-related Management API operations. | Yes |
| Create a new workflow | `WORKFLOW_CREATE` | Required for workflow creation mutations. | No |
| Update a workflow | `WORKFLOW_UPDATE` | Required for workflow update mutations. | No |
| Delete a workflow | `WORKFLOW_DELETE` | Required for workflow deletion mutations. | No |
| Create a new workflow step | `WORKFLOW_STEP_CREATE` | Required for workflow step creation mutations. | No |
| Update a workflow step | `WORKFLOW_STEP_UPDATE` | Required for workflow step update mutations. | No |
| Delete a workflow step | `WORKFLOW_STEP_DELETE` | Required for workflow step deletion mutations. | No |

### PATs - Users & team

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Invite a user into an existing project | `USER_INVITE` | Required for project member invite mutations. Studio UI is controlled by custom roles. | No |
| Assign a role to a user | `USER_ASSIGNROLE` | Required for role-assignment mutations on project members. | No |
| Remove a user from an existing project | `USER_REMOVE` | Required for removing members from a project via the Management API. Also required for `deleteAgent` mutations. | No |

### PATs - User roles

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create new roles | `ROLE_CREATE` | Required for custom role creation mutations. Studio UI is controlled by custom roles. | No |
| Update existing roles | `ROLE_UPDATE` | Required for role update mutations (including management and content permissions on roles). | No |
| Delete an existing role | `ROLE_DELETE` | Required for custom role deletion mutations. | No |

### PATs - Experimental, AI, usage

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Allows managing experimental features and their role assignments | `MANAGE_EXPERIMENTAL_FEATURES` | Required for experimental-feature management mutations. | No |
| Create AI guidelines | `AI_GUIDELINE_CREATE` | Required for AI guideline creation mutations. | No |
| Read AI guidelines | `AI_GUIDELINE_READ` | Required for AI guideline queries. | No |
| Update AI guidelines | `AI_GUIDELINE_UPDATE` | Required for AI guideline update mutations. | No |
| Delete AI guidelines | `AI_GUIDELINE_DELETE` | Required for AI guideline deletion mutations. | No |
| Read observability data | `OBSERVABILITY_READ` | Required for observability read operations exposed by the Management API. | No |

### PATs - Agents

<Alert theme="info">
**Invite a new agent**, **Remove an agent**, **Delete an agent config**, and **Trigger an agent run** can be assigned to a PAT but have no effect on Management API access today.
</Alert>

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Create a new agent config | `AGENT_CONFIG_CREATE` | Required for `createAgent` mutations. | No |
| Read agent config | `AGENT_CONFIG_READ` | Required for agent configuration queries. | No |
| Update an agent config | `AGENT_CONFIG_UPDATE` | Required for `updateAgent` mutations. | No |

### PATs - Integrations & extensions

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Can add new integrations to an existing project | `INTEGRATION_CREATE` | Required for integration creation mutations. | No |
| Can see existing integrations in an existing project | `INTEGRATION_READ` | Required for integration queries. | No |
| Can update existing integrations in an existing project | `INTEGRATION_UPDATE` | Required for integration update mutations. | No |
| Can delete existing integrations in an existing project | `INTEGRATION_DELETE` | Required for integration deletion mutations. | No |
| Can trigger a netlify build for an existing integration | `NETLIFY_TRIGGER_BUILD` | Required for Netlify build trigger mutations on integrations. | No |
| Can add new extension to an existing project | `EXTENSION_CREATE` | Required for extension creation mutations. | No |
| Can see existing extensions in an existing project | `EXTENSION_READ` | Required for extension queries. | No |
| Can update existing extensions in an existing project | `EXTENSION_UPDATE` | Required for extension update mutations. | No |
| Can delete existing extensions in an existing project | `EXTENSION_DELETE` | Required for extension deletion mutations. | No |

### PATs - App installations

| Permission name | Action | Description | PAT default |
|-----------------|--------|-------------|---------------|
| Can add app installations | `APP_INSTALLATION_CREATE` | Required for app installation mutations. Studio banners and selectors are controlled by custom roles. | No |
| Can update app installations | `APP_INSTALLATION_UPDATE` | Required for app installation update mutations. | No |
| Can delete app installations | `APP_INSTALLATION_DELETE` | Required for app uninstall mutations. | No |

### PATs - Legacy Management API content permissions

| Permission name | Action | Description | Alternative |
|-----------------|--------|-------------|-----------------|
| Read existing entries | `CONTENT_READ` | Deprecated. No effect on Content API reads for PAT-authenticated requests. | [Content API permissions — Read](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) on the PAT |
| Create new entries | `CONTENT_CREATE` | Deprecated. Does not grant Content API **Create** for the PAT. | [Content API permissions — Create](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Delete existing entries | `CONTENT_DELETE` | Deprecated. Does not grant Content API **Delete** for the PAT. | [Content API permissions — Delete](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Publish non-published entries | `CONTENT_PUBLISH` | Deprecated. Does not grant Content API **Publish** for the PAT. | [Content API permissions — Publish](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Update existing non published entries | `CONTENT_UPDATE` | Deprecated. Does not grant Content API **Update** for the PAT. | [Content API permissions — Update](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |
| Update published entries | `CONTENT_UPDATE_PUBLISHED` | Deprecated. Does not grant Content API **Update** or **Unpublish** for the PAT. | [Content API permissions — Update or Unpublish](/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions) |

---
# User roles and permissions

Source: https://hygraph.com/docs/getting-started/access-and-permissions/user-roles-and-permissions

Roles determine what users can see and do in your Hygraph project. Each role carries a set of **content permissions**, which govern access to content entries, and **Management API permissions**, which determine what a user can do in the UI and through the API.

<Alert theme="info">
**Content permissions are environment-specific.** Their configuration is applied per environment. If you are working with multiple environments, configure content permissions separately for each one.

**Management API permissions are global.** They apply across all environments in a project.
</Alert>

Hygraph provides five built-in system roles and supports custom roles for projects on enterprise plans. To access roles and permissions, navigate to **Project Settings > Team > Roles & Permissions**.

![Roles and Permissions overview](/images/docs/user-guides/roles-and-permissions/roles-and-permissions-overview.png)

## System roles

System roles are built into every Hygraph project. They cannot be edited or deleted.

| Role        | Rights                                                                                       |
|-------------|----------------------------------------------------------------------------------------------|
| Owner       | All Admin rights, plus the ability to change billing settings and delete the project.        |
| Admin       | All Developer rights, plus the ability to manage team members and create or update projects. |
| Developer   | All Editor rights, plus the ability to create, update, and delete models and enumerations.   |
| Editor      | All Contributor rights, plus the ability to delete content.                                  |
| Contributor | Ability to create and update content.                                                        |

Only **Admins** and **Owners** can view the permissions granted to each role or assign team members to roles.

## Custom roles

<Alert theme="warning">
Custom roles are available on enterprise plans only.
</Alert>

Custom roles let you define exactly what a user can see and do, without exposing features that are not relevant to their work. Only project **Admins** and **Owners** can create and manage custom roles.

When configuring a custom role, always include the **Read** and **Read versions** content permissions. Without **Read**, users cannot open content entries. Without **Read versions**, versioning will not display correctly in the content editor.

### Create a custom role

1. Click **+ Add custom role** at the top right of the roles screen.
2. Enter a **Name** for the role and optionally a **Description**.
3. Click **Create**.

![Add custom role](/images/docs/user-guides/roles-and-permissions/add-custom-role.png)

The new role is added to the list with basic read permissions assigned by default. Use **View permissions** from the context menu to configure the full permission set.

From the context menu of a custom role, you can:

- **View permissions**: View and edit the content and Management API permissions for this role.
- **Assign members**: Assign project members to this role.
- **Delete role**: Permanently delete this role.

### Configure content permissions

Content permissions determine what actions users can perform on content entries in the content editor.

![Add Content permissions](/images/docs/user-guides/roles-and-permissions/add-content-permission.png)

1. Click on the custom role in the roles table to open its permissions screen.
2. Click **+ Add permission**.
3. Use the **Model** dropdown to select the model to apply permissions to. Select **All** to apply them across all models.
4. Use the checkboxes to select the actions to grant. Some actions reveal additional options for **Locales** and **Stages**.
5. Click **Create** to save.

| Permission      | What it allows                                                      |
|-----------------|---------------------------------------------------------------------|
| `Read`          | View content entries. Required as a baseline for all other actions. |
| `Create`        | Create new content entries.                                         |
| `Update`        | Edit existing content entries.                                      |
| `Delete`        | Delete content entries.                                             |
| `Publish`       | Publish content entries to a stage.                                 |
| `Unpublish`     | Remove content entries from a published stage.                      |
| `Read versions` | View version history for a content entry.                           |

Use the **Reset** button at the bottom left of the screen to reset permissions to their default state before saving.

### Configure Management API permissions

Management API permissions control both API access and UI visibility.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvnkhv4t07vxd8gz8lum" caption="Edit Management API permissions" />

1. Click on the custom role in the roles table.
2. The screen shows only enabled permissions by default. Click **Show all available permissions** to see the full list.
    - For a complete reference of all available Management API permissions, see the [Management API permissions reference](/docs/getting-started/access-and-permissions/management-api-permissions).
3. Use the toggles to enable or disable individual permissions.
4. Use the checkboxes to select multiple permissions. The **Enable selected** or **Disable selected** bulk action appears at the top of the table.

For a **read-only role**, the default permissions are sufficient. No additional Management API permissions are needed.

For a **publisher role**, also enable **Update published entries**, **Create new entries**, **Publish non-published entries**, **Update existing non-published entries**, and **Delete existing entries**.

### Delete a custom role

System roles cannot be deleted. To delete a custom role:

1. Open the context menu for the role.
2. Select **Delete role**.
3. Confirm the deletion in the popup.

This action cannot be undone.

![Delete a custom role](/images/docs/user-guides/roles-and-permissions/delete-role.png)

## Assign members to a role

Before assigning a user to a role, they must be invited to the project. See [Manage team members](/docs/getting-started/access-and-permissions/manage-team-members) for instructions.

To assign team members to a role:

1. Open the context menu for the role and select **Assign members**.
2. Select one or more team members using the checkboxes.
3. Click **Assign**.

If all current project members are already assigned to the role, a popup will let you know. Click **Invite members** in that popup to add new people to the project.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvjpjbsa07w5tieg1a0i" caption="Assign members to a custom role" />

## View role permissions

To view all content and Management API permissions for a role, open the context menu and select **View permissions**.

From the permissions screen you can:

- Sort permissions alphabetically by model or action.
- Filter permissions by action, model, locale, and stage.
- Assign new members to the role by clicking **Assign members** at the top right.

Permissions for system roles are read-only. To edit permissions, use a [custom role](#custom-roles).

## Remove a user

To remove a team member from a role or from the project entirely, go to **Project Settings > Team > Members**. See [Manage team members](/docs/getting-started/access-and-permissions/manage-team-members#remove-a-members-role) for full instructions.

## Permission setup examples

The following examples show common permission configurations. 

<Alert theme="info" title="Pro tip">
Use the browser find command (`Ctrl+F` or `Cmd+F`) to locate specific permission names in the Management API permissions reference.
</Alert>

### Read-only

Content API permissions:

- **Model:** All
- **Read:** All locales, all stages
- **Read versions:** Enabled

No additional Management API permissions are needed. The defaults are sufficient for a read-only role.

![Read-only user](/images/docs/user-guides/roles-and-permissions/setup-example-read-only.png)

### Read and publish

Content API permissions:

- **Model:** All
- **Read:** All locales, all stages
- **Publish:** All stages, all destination stages, all locales
- **Read versions:** Enabled

Additional Management API permissions to enable:

- `Update published entries`
- `Create new entries`
- `Publish non-published entries`
- `Update existing non-published entries`
- `Delete existing entries`

![Read and publish setup](/images/docs/user-guides/roles-and-permissions/setup-example-read-and-publish.png)

### By model

Select the target model from the **Model** dropdown when creating a content permission. Permissions will apply only to entries of that model.

![Setup by models](/images/docs/user-guides/roles-and-permissions/setup-example-models.png)

<Alert theme="warning">

Selecting multiple models at once is not supported, unless you select all models. To configure the same permissions on two different models, create a separate permission for each.

If the target model references other models, you must also add at least **Read** and **Update** permissions on each referenced model for actions like create, update, delete, publish, or unpublish to work correctly.
</Alert>

### By locale

When selecting a permission action, use the **Locales** dropdown to restrict it to one or more specific locales.

![Setup by locales](/images/docs/user-guides/roles-and-permissions/setup-example-locales.png)

<Alert theme="info">

You must also grant access to the default locale for any role that needs to create or update content.
</Alert>

### By content stage

Use the **From stages** and **To stages** dropdowns to restrict publish and unpublish actions to specific stages. For example, you can limit a role to publishing from **Draft** to a **QA** stage only, preventing direct publishing to **Published**.

![Setup by content stage](/images/docs/user-guides/roles-and-permissions/setup-example-content-stage.png)

<Alert theme="info" title="Pro tip">
Check out [Content Workflows](/docs/developer-guides/project/content-workflows) to learn how to use content stages for approval workflows. For help with a specific setup, contact the Hygraph support team.
</Alert>

### By environment

Management API permissions apply to all environments in a project. Content permissions are environment-specific, so you can configure different permissions on each environment for the same role.

For example, to give a role read-only access on the master environment and publish access on a secondary environment:

1. Switch to your master environment.
2. Set up the role as read-only, as described in the [read-only example above](/docs/getting-started/access-and-permissions/user-roles-and-permissions#read-only).
3. Switch to the secondary environment. [Learn how to switch environments](/docs/developer-guides/project/manage-project-environments#switch-environments).
4. Open the custom role and select **View permissions**.
5. Add the **Publish** and **Unpublish** content permissions.
6. Enable the additional Management API permissions required for publishing, as described in the [read and publish example above](/docs/getting-started/access-and-permissions/user-roles-and-permissions#read-and-publish).

![Setup by environment](/images/docs/user-guides/roles-and-permissions/setup-example-content-stage.png)

### Using conditions

Conditions let you restrict a permission to specific content entries. Instead of granting a role access to all entries in a model, you can scope it further using a GraphQL `where` clause. 
For example, for entries with a particular field value, tag, or ID.

To add a condition when configuring a content permission:

1. Open the custom role and click **+ Add permission**.
2. Select the target model from the **Model** dropdown.
3. Check the actions you want to grant.
4. Enter a JSON `where` clause in the **Condition** field.
5. Click **Create** to save.

![Conditions](/images/docs/user-guides/roles-and-permissions/setup-example-conditions.png)

Conditions must be maintained manually. If a field is renamed or a referenced document ID changes, the condition becomes invalid. Update affected conditions whenever the underlying schema or content changes.

For the full conditions reference including syntax, examples, and constraints, see [Use conditions](/docs/getting-started/access-and-permissions/content-api-permissions#use-conditions) in the content permissions documentation.

<Alert theme="warning">
Conditions require familiarity with GraphQL `where` clauses. Use the API Playground to build
and test a condition before applying it to a role.
</Alert>

## What's next

- [Manage team members](/docs/getting-started/access-and-permissions/manage-team-members): Invite members and manage project access.
- [Content permissions](/docs/getting-started/access-and-permissions/content-api-permissions): Detailed reference for content permission rules, limits, and conditions.
- [Management API permissions](/docs/getting-started/access-and-permissions/management-api-permissions): Full reference for all Management API permission options.
- [Authorization](/docs/api-reference/basics/authorization): Public API permissions, PATs, and endpoints.

---
# Hygraph account settings

Source: https://hygraph.com/docs/getting-started/account-settings

Account settings let you manage the core details of your Hygraph account, including personal information and notifications. These settings apply across all projects you have access to.

At the top right of the screen, click your avatar and select **Account settings**.

![Account settings](/images/docs/getting-started/fundamentals/project-directory-supports-and-settings.png)

Account settings apply to your user account. Project-specific configuration is managed separately within each project.

## Profile information

Your profile contains basic information associated with your account, such as your name and email address. This information is used across Hygraph for identification and collaboration.

Some fields, like your email address, may be managed by your identity provider if your organization uses Single Sign-On (SSO).

## Notifications

Use notification settings to choose whether Hygraph notifies you about replies, mentions, assignments, and status updates through email or in-app notifications.

You can adjust these preferences at any time to match your workflow.

## Update your password

To change your account password, you will need to log out and choose **Forgot your password** on the login page to receive an email for setting a new one.

If you've logged in with GitHub or Google, you can change your password there and you'll be logged in automatically with Hygraph.

## Delete your account

You can permanently delete your Hygraph account from the account settings page.

Deleting your account is irreversible and removes your personal access to Hygraph. Any projects you own will be deleted, while projects you are a member of will remain active for other members.


---
# Hygraph overview

Source: https://hygraph.com/docs/getting-started/index

Hygraph is a GraphQL-native structured content platform, also referred to as a headless CMS, built to model, govern, and deliver content across every brand, channel, and market. This page covers what Hygraph is, how the platform is structured, and what capabilities are available to your team.

## What is Hygraph?

Hygraph gives development and content teams a single, governed foundation for structuring, creating, and delivering content programmatically. Content is modeled as structured entities and relationships, not pages, so it can be reused, governed, and delivered anywhere: any frontend, any backend, through one GraphQL API. Content Federation extends that same API to external systems, so data from commerce platforms, PIMs, and third-party APIs is queryable alongside your own content.

Your schema lives in one place. Your content can come from anywhere. Your frontend is your choice.

## How it works

Hygraph projects follow a consistent structure across three layers.

### Schema

You define your content structure by creating models, adding fields, and configuring relationships between them. Models can include reusable components, remote data sources, and sidebar widgets for custom editorial tools. 

### Content

Once your schema is set, teams create and manage entries in the Content Editor. Entries move through configurable stages (such as `Draft` and `Published`), and you can schedule publishing, bundle entries into releases, and assign collaborative workflows to ensure the right people review content before it goes live. Editors can preview content in context using Live Preview, and make field-level edits directly from a frontend page using Click-to-Edit.

### Delivery

Hygraph exposes your content through a globally distributed GraphQL API. You query your own content and federated remote sources in a single request.

## Platform capabilities

The sections below map the capabilities available across Hygraph by area.

### Content modeling

The **Schema Builder** supports scalar fields, relational fields, union types, enumerations, components, and remote sources. Conditional fields let you show or hide fields in the editor based on values entered elsewhere in the entry, keeping complex models manageable for editorial teams.

Use taxonomies to define hierarchical classification structures, such as tags, categories, and facets that apply consistently across content types. Use variants to define audience-specific versions of content entries without duplicating content entries.

### Editorial experience

The content editor supports localization, scheduled publishing, release management, and collaborator view, which shows when another user is editing the same entry. Quick filters and Content Finder reduce the time it takes to locate entries across large projects.

### AI capabilities

AI Assist lets editors generate, improve, and localize content through natural language prompts inside the entry form.

AI Agents automate repetitive editorial tasks, such as translation, SEO analysis, and content summarization, directly inside your Hygraph project. You can trigger an agent manually on selected entries, or configure it to run automatically when an entry moves through a workflow step. When an agent completes its task, the entry enters a read-only review state where the editor can approve or revert each field change before editing resumes.

### Visual editing

Live Preview displays a preview of your frontend alongside the content editor, so changes are visible without publishing. With Click-to-Edit, editors can hover over any element in your preview, click **Edit**, and the editor opens at the exact field. 

### Asset management

The Assets manager handles uploads, transformations, and delivery for images, video, and documents. Asset transformations, such as resizing, format conversion, and cropping, apply at the API level via URL parameters, so you don't need a separate tool to manage image delivery.

### Content Federation

Remote sources connect external REST or GraphQL APIs to your Hygraph schema. Once configured, remote data is queryable through the same GraphQL endpoint as your local content. Top-level remote fields let you fetch remote content directly without anchoring it to a Hygraph model.

### Developer tools

Hygraph provides a Content API for content delivery, a Management SDK for programmatic schema and content operations, and Webhooks for event-driven integrations. 

The App Framework lets you build custom field extensions, sidebar elements, and third-party integrations tailored to your project. The MCP Server exposes Hygraph to MCP-compatible AI tools.

### Access and governance

Granular permissions let administrators define role-based access at the model, field, stage, and locale level. Content workflows add structured approval steps to content creation, so entries pass through defined checkpoints before publication. Audit logs record all actions, including those performed via app tokens, PATs, and third-party integrations.

## Use cases

Hygraph is built for organizations where content spans more than one brand, market, or system.

- **Multi-Brand Enterprises**: One governed content foundation for every brand, replacing separate CMS instances per brand.
- **eCommerce Across Regions & Languages**: Structured product content, localized and delivered via GraphQL, without duplicating entries per market.
- **AI Operations & Agentic Content**: A structured content graph AI agents can reliably consume, connected via MCP within governed boundaries.
- **B2B Portals & Audience Targeting**: Role-based content delivery, by account, region, or entitlement, built into the model, not the frontend.

## What's next

- [Quickstart](/docs/getting-started/quickstart): Create your first project, define a schema, and query content.
- [Studio walkthrough](/docs/getting-started/studio-walkthrough): Get oriented with the Hygraph interface and where key features live.
- [eCommerce tutorial](/docs/getting-started/tutorial/tutorial-overview): Build a complete Hygraph project from schema to connected frontend.

---
# Migrate to Hygraph

Source: https://hygraph.com/docs/getting-started/migrating-to-hygraph

Migrating to Hygraph involves two distinct phases: rebuilding your schema, then importing your content. Hygraph gives you the Management SDK and Content API to handle both programmatically, as well as a UI-based option for schema creation.

This guide covers the full migration flow, from exploring your existing data to importing content, along with tips for specific field types such as assets, rich text, and relations.

## Prerequisites

- An active Hygraph project
- A [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens) with Management API access (for schema creation via the SDK)
- A Permanent Auth Token with Content API mutations enabled (for content import)
- An export of your existing content in JSON or CSV format

## Step 1: Explore your current data

Before creating anything in Hygraph, examine the structure of your existing project and map it to Hygraph's data model.

![Plan your schema](/images/docs/getting-started/fundamentals/plan-your-schema.png)

Work through the following questions:

- What models and fields do you currently have, and how do they map to [Hygraph's field types](/docs/api-reference/schema/field-types)?
- How do your models relate to each other?
- Are there structures you want to normalize or improve as part of the migration?
- Which data belongs in Hygraph, and which belongs elsewhere? For example, you may want image assets in Hygraph but video assets in a dedicated streaming service.

Export your existing content to JSON or CSV so you can inspect field names, content types, and relations.

The examples in this guide use the following CSV of authors:

```csv
oldId,firstName,lastName
1,Stephen,King
2,Frank,Herbert
3,Brian,Herbert
4,Kevin,Anderson
5,Agatha,Christie
6,Haruki,Murakami
7,Isaac,Asimov
```

Hygraph supports over a dozen [field types](/docs/api-reference/schema/field-types), from strings, booleans, and dates to polymorphic union types and remote field resolvers. You get a small set of [system fields](/docs/api-reference/schema/system-fields) out of the box, but everything else is defined by you.

<Alert theme="info" title="On schema normalization">
Some teams use migration as an opportunity to restructure their schema, for example, extracting repeated content into components. This can improve efficiency, but may require manual intervention when importing content. If you skip normalization for now, you can use `String` and `JSON` fields to represent most data without modification, though you will lose some filtering capability at the API level.
</Alert>

## Step 2: Create your schema

![Create your schema](/images/docs/getting-started/fundamentals/create-your-schema.png)

Create your schema before importing any content. You have two options: the Management SDK or the Hygraph UI. The SDK is faster for large or complex schemas and gives you a repeatable record of what was created.

### Use the Management SDK

The [Management SDK](/docs/api-reference/management-sdk/management-sdk) lets you create models, fields, enumerations, components, and remote sources programmatically. All changes are submitted as a single transaction. If any operation fails, the entire batch rolls back automatically.

**Install the SDK:**
```bash
npm install @hygraph/management-sdk
```

**Initialize the client:**

```ts
const { Client } = require('@hygraph/management-sdk');

// endpoint is your High Performance Content API URL
// found in Project Settings > Endpoints > High Performance Content API
const client = new Client({
  authToken,
  endpoint,
  name, // optional
});
```

Use `createModel` to create a model:
```js
client.createModel({
  apiId: '<your_api_id>',
  apiIdPlural: '<your_api_id_plural>',
  description: '<your_model_description>',
  displayName: '<Your model name>',
});
```

To create two models, `Author` and `Book`:
```js
client.createModel({
  apiId: 'Author',
  apiIdPlural: 'Authors',
  displayName: 'Author',
});

client.createModel({
  apiId: 'Book',
  apiIdPlural: 'Books',
  displayName: 'Book',
});
```

Use `createSimpleField` to add fields to a model. The example below shows all available options. Use only the ones you need:
```js
client.createSimpleField({
  apiId: '<your_api_id>',
  description: '<your_description>',
  displayName: '<your_display_name>',
  embeddableModels: '<embeddable_models>',
  embedsEnabled: '<boolean>',
  formConfig: '<form_config_json>',
  formExtension: '<form_extension>',
  formRenderer: '<form_renderer>',
  isHidden: '<boolean>',
  isList: '<boolean>',
  isLocalized: '<boolean>',
  isRequired: '<boolean>',
  isTitle: '<boolean>',
  isUnique: '<boolean>',
  migrationValue: '<migration_value>',
  parentApiId: '<parent_api_id>',
  position: '<int>',
  tableConfig: '<table_config_json>',
  tableExtension: '<table_extension>',
  tableRenderer: '<table_renderer>',
  type: SimpleFieldType.STRING,
  validations: '<SimpleFieldValidationsInput>',
  visibility: '<VisibilityTypes>',
});
```

To add a required string field to the `Author` model:
```js
client.createSimpleField({
  parentApiId: 'Author',
  type: SimpleFieldType.STRING,
  apiId: 'favoritePastime',
  displayName: 'Author Favorite Pastime',
  isRequired: true,
  visibility: VisibilityTypes.ReadWrite,
});
```

**Full migration example**

The script below creates an `Author` model with `firstName` and `lastName` fields:
```js
// migration.js
const { Client, SimpleFieldType } = require('@hygraph/management-sdk');

const client = new Client({
  authToken: '<your_permanent_auth_token>',
  endpoint: '<your_content_api_endpoint>',
});

// Create the Author model
client.createModel({
  apiId: 'Author',
  apiIdPlural: 'Authors',
  displayName: 'Author',
});

// Add firstName field to Author
client.createSimpleField({
  parentApiId: 'Author',
  apiId: 'firstName',
  displayName: 'First Name',
  type: SimpleFieldType.STRING,
});

// Add lastName field to Author
client.createSimpleField({
  parentApiId: 'Author',
  apiId: 'lastName',
  displayName: 'Last Name',
  type: SimpleFieldType.STRING,
});

// Preview all changes before committing
const changes = client.dryRun();
console.log(changes);
```

Run the script from the command line:
```bash
node migration.js
```

Review the `changes` array to confirm the operations that will be applied. Once you are satisfied, replace `dryRun()` with `run()` to commit the changes:
```js
async function runMigration() {
  const result = await client.run(true);

  if (result.errors) {
    throw new Error(result.errors);
  }

  console.log(result.name);
}

runMigration();
```

Once the migration runs, verify the result by checking the schema editor in Hygraph or <Link href="https://graphql.org/learn/introspection/" target="_blank">introspecting</Link> your endpoint.

If your schema includes components, enumerations, or remote source fields, create those at the schema level before adding them to models. See the [Management SDK field creation examples](/docs/api-reference/management-sdk/management-sdk-field-examples) for instructions.

**Additional resources:**
- [Management SDK quickstart](/docs/api-reference/management-sdk/management-sdk-quickstart)
- [Management SDK methods reference](/docs/api-reference/management-sdk/management-sdk-methods-reference)
- [Management SDK full example](/docs/api-reference/management-sdk/management-sdk-example)
- [Batch migrations](/docs/api-reference/management-sdk/management-sdk-batchmigration)

### Use the UI

To create your schema in the Hygraph UI, navigate to the schema editor and create your models, then add fields to each one. The [getting started guide](/docs/getting-started/quickstart) covers creating models and adding fields.

## Step 3: Plan your content migration

With your schema in place, review your existing content and map it to the new structure before importing anything.

Order matters when content is relational. For example, you must create asset entries before creating content entries that reference them, otherwise the relation cannot be established at import time.

As you plan, identify:

- Which content needs to be migrated first to unblock dependent content
- Which content is critical vs. supporting, so you can prioritize accordingly
- Where the shape of your existing data differs from your new input types, and what transformation is needed

## Step 4: Import your content

Import assets before content entries. Relations cannot be established until the assets they reference exist. How you upload assets depends on which asset system your project uses.

![API Endpoints](/images/docs/getting-started/fundamentals/api-endpoints-location.png)

### Assets

Projects created after February 2024 use the Hygraph Asset Management system. Projects older than that use the Legacy asset system. The upload process differs between the two:

- **Hygraph Asset Management:** Asset uploads are part of the native GraphQL API. Upload through `createAsset` mutations instead.
- **Legacy asset system:** Uses a dedicated HTTP upload endpoint at `/upload` appended to your project URL.

To check which system your project uses, navigate to **Project Settings > Access > Endpoints** and look for an asset upload endpoint. If one is listed, your project uses the legacy system. If not, it uses Hygraph Asset Management.

You will need a [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens) with **Mutations** access enabled to upload assets.

<Alert theme="warning">
File size limits depend on your plan. <Link href="https://hygraph.com/pricing" target="_blank">Check the pricing page</Link> for details.
</Alert>

Assets follow the same [environment](/docs/api-reference/basics/environments) and [authorization](/docs/api-reference/basics/authorization) settings as all other content in your project.

After uploading, [publish your assets](/docs/api-reference/assets/publishing-assets) before they can be served alongside published content. For full asset upload documentation, see [Uploading assets](/docs/api-reference/assets/uploading-assets).

**Upload by file — Hygraph Asset Management**

First, create the asset via mutation to receive the upload URL and credentials:

<Tabs panelHeight={380}>
  <TabsItem label="Mutation">
```graphql
mutation createAsset {
  createAsset(data: {}) {
    id
    url
    upload {
      status
      expiresAt
      error {
        code
        message
      }
      requestPostData {
        url
        date
        key
        signature
        algorithm
        policy
        credential
        securityToken
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">
```json
{
  "data": {
    "createAsset": {
      "id": "clt47n0t600j807vvirlzi1xx",
      "url": "https://eu-central-1.graphassets.com/clpqzrnm4007e01t810b59ir4/clt47n0t600j907vveibipmov",
      "upload": {
        "status": "ASSET_CREATE_PENDING",
        "expiresAt": "2024-02-27T12:38:49+00:00",
        "error": null,
        "requestPostData": {
          "url": "https://eu-1-assets-delivery-hg75hf.s3.eu-central-1.amazonaws.com",
          "date": "20240227T101349Z",
          "key": "clpqzrnm4007e01t810b59ir4/upload/...",
          "signature": "c17e7b1c5d4af665a8fc74421fae53b72e94bb19e85e7befd1eb79b865bef7d2",
          "algorithm": "AWS4-HMAC-SHA256",
          "policy": "eyJleHBpcmF0aW9uIjo...",
          "credential": "ASIAVQRE3VMEWGY5C2XL/20240227/eu-central-1/s3/aws4_request",
          "securityToken": "IQoJb3JpZ2luX2Vj..."
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

Then upload the file using the credentials from the response:
```bash
curl --request POST \
  --url $URL \
  --form X-Amz-Date=$DATE \
  --form key=$KEY \
  --form X-Amz-Signature=$SIGNATURE \
  --form X-Amz-Algorithm=$ALGORITHM \
  --form policy=$POLICY \
  --form X-Amz-Credential=$CREDENTIAL \
  --form X-Amz-Security-Token=$SECURITY_TOKEN \
  --form file=@./test.jpg
```

**Upload by remote URL — Hygraph Asset Management**
```graphql
mutation uploadByUrl {
  createAsset(
    data: {
      uploadUrl: "https://images.unsplash.com/photo-1682687218147-9806132dc697"
    }
  ) {
    id
    url
  }
}
```

**Upload by file — legacy asset system**

<Tabs panelHeight={200}>
  <TabsItem label="cURL">
```bash
curl -XPOST -H "Authorization: Bearer {YOUR_PAT_VALUE}" -F fileUpload=@picture.jpg https://[region].hygraph.com/v2/[projectId]/[environment]/upload
```

  </TabsItem>
  <TabsItem label="Node.js">
```js
// File must use the .mjs extension, as node-fetch is an ESM-only package.
import fetch, { FormData, fileFrom } from 'node-fetch';

const form = new FormData();

form.set('fileUpload', await fileFrom('path/to/file.png'));

fetch(`${process.env.HYGRAPH_URL}/upload`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HYGRAPH_ASSET_TOKEN}`,
  },
  body: form,
})
  .then((res) => res.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)))
  .catch((err) => console.log(err));
```

  </TabsItem>
  <TabsItem label="JavaScript">
```js
const HYGRAPH_URL = '';
const HYGRAPH_ASSET_TOKEN = '';

async function upload() {
  const input = document.getElementById('fileUpload');
  const file = input.files[0];

  const form = new FormData();
  form.append('fileUpload', file);

  // Do not expose HYGRAPH_ASSET_TOKEN in front-end code in production.
  // Use a backend service to handle uploads and keep the token server-side.
  const response = await fetch(`${HYGRAPH_URL}/upload`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${HYGRAPH_ASSET_TOKEN}`,
    },
    body: form,
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
}
```

  </TabsItem>
  <TabsItem label="Response">
```json
{
  "filename": "pexels-photo-1170986.jpeg",
  "mimetype": "image/jpeg",
  "size": 32476,
  "width": 500,
  "height": 750,
  "url": "https://media.graphassets.com/P3TkBzxyQLupgDWNFydB",
  "id": "ckfdz530o0001ip92cdr3bbmj"
}
```

  </TabsItem>
</Tabs>

**Upload by remote URL — legacy asset system**

<Tabs panelHeight={200}>
  <TabsItem label="cURL">
```bash
curl -XPOST -d url=https://media.graphassets.com/P3TkBzxyQLupgDWNFydB https://[region].hygraph.com/v2/[projectId]/[environment]/upload
```

  </TabsItem>
  <TabsItem label="Node.js">
```js
// File must use the .mjs extension, as node-fetch is an ESM-only package.
import fetch from 'node-fetch';

fetch(`${process.env.HYGRAPH_URL}/upload`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HYGRAPH_ASSET_TOKEN}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: `url=${encodeURIComponent(
    'https://media.graphassets.com/P3TkBzxyQLupgDWNFydB'
  )}`,
})
  .then((res) => res.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)))
  .catch((err) => console.log(err));
```

  </TabsItem>
  <TabsItem label="Response">
```json
{
  "filename": "pexels-photo-1170986.jpeg",
  "mimetype": "image/jpeg",
  "size": 32476,
  "width": 500,
  "height": 750,
  "url": "https://media.graphassets.com/J9BOEF3OSuuSXDhvriQa",
  "id": "ckgs20b80017109547vfev24c"
}
```

  </TabsItem>
</Tabs>

### Content entries

To find your Content API endpoint, go to **Project Settings > Access > Endpoints > High Performance Content API**.

Use [GraphQL mutations](/docs/api-reference/content-api/mutations#auto-generated-mutations) to create content entries. Hygraph auto-generates mutations for every model you create. Because existing data rarely maps 1:1 to your new schema, you will likely need to transform your dataset to match your new input types before importing.

The script below shows a complete import example using the [CSV authors file from Step 1](#step-1-explore-your-current-data):
```js
// Import necessary libraries
const { GraphQLClient, gql } = require('graphql-request');
const csvToJson = require('csvtojson');

require('dotenv').config();

// Initialize GraphQL client
const client = new GraphQLClient(process.env.HYGRAPH_ENDPOINT, {
  headers: {
    authorization: `Bearer ${process.env.HYGRAPH_TOKEN}`,
  },
});

// Build a mutation from a data row
function createMutation(data) {
  return gql`
    mutation MyMutation {
      createAuthor(data: {
        firstName: "${data.firstName}",
        lastName: "${data.lastName}",
        oldId: "${data.oldId}"
      }) {
        id
      }
    }
  `;
}

// Run the migration
async function run() {
  // Load and parse the CSV
  const data = await csvToJson().fromFile('./data.csv');

  // Build mutations from each row
  const mutations = data.map((item) => createMutation(item));

  // Execute each mutation with a 1-second delay between requests
  mutations.forEach((mutation, index) => {
    setTimeout(() => {
      console.log(`Running mutation ${index + 1} of ${mutations.length}`);
      client.request(mutation).then((response) => {
        console.log(response);
      });
    }, (index + 1) * 1000);
  });
}

run();
```

See [rate limits](/docs/api-reference/basics/rate-limits) for guidance on request frequency.

### Rich text

Hygraph stores rich text as an Abstract Syntax Tree (AST) based on <Link href="https://docs.slatejs.org/" target="_blank">Slate</Link>. If your existing content stores rich text as HTML or another format, you need to convert it before importing.

1. **Convert:** Use <Link href="https://github.com/hygraph/rich-text/tree/main/packages/html-to-slate-ast" target="_blank">Hygraph's HTML-to-Slate AST converter</Link> to transform your existing rich text into the correct AST format.
2. **Import:** Use a `create` mutation with a `RichTextAST` variable to import the converted content.

<Tabs panelHeight={280}>
  <TabsItem label="Mutation">
```graphql
mutation createArticle($title: String, $content: RichTextAST) {
  createArticle(data: {
    title: $title,
    content: $content
  }) {
    title
    content {
      raw
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Variables">
```json
{
  "title": "Working with the Hygraph Rich Text field",
  "content": {
    "children": [
      {
        "type": "paragraph",
        "children": [
          {
            "text": "Hygraph boasts an impressive collection of "
          },
          {
            "href": "https://hygraph.com/docs/api-reference/schema/field-types",
            "type": "link",
            "children": [{ "text": "Field Types" }]
          },
          {
            "text": " that you can use when content modeling."
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

For additional rich text utilities, see the <Link href="https://github.com/hygraph/rich-text" target="_blank">Hygraph rich text helpers</Link>.

### Relations

There are two approaches to migrating relational content.

**Option 1: Create with nested mutations**

Use a [create mutation](/docs/api-reference/content-api/mutations#create-entries) with a nested create to build both sides of a relation in one request. For subsequent entries that share the same related record, use a `connect` mutation instead of creating a duplicate.

**Option 2: Create separately, then connect**

Create all entries for each model first using [create mutations](/docs/api-reference/content-api/mutations#create-entries), then wire them together using [update mutations](/docs/api-reference/content-api/mutations#update-entries) or [update many mutations](/docs/api-reference/content-api/mutations#update-many). This approach is more straightforward but requires more total mutations.

<Alert theme="warning">
Option 2 requires more mutations to be sent. Review the [rate limits](/docs/api-reference/basics/rate-limits) documentation before choosing your approach.
</Alert>

<Tabs panelHeight={900}>
  <TabsItem label="create">
```graphql
# Create a book with a new author (one relation)
mutation createOneRelation {
  createBook(
    data: {
      name: "Rose madder"
      slug: "rose-madder"
      price: 30
      author: { create: { name: "Stephen King", slug: "stephen-king" } }
    }
  ) {
    id
    name
    author {
      name
    }
  }
}

# Create a book with multiple new authors
mutation createManyRelations {
  createBook(
    data: {
      name: "The road to Dune"
      slug: "the-road-to-dune"
      price: 30
      authors: {
        create: [
          { name: "Frank Herbert", slug: "frank-herbert" }
          { name: "Brian Herbert", slug: "brian-herbert" }
          { name: "Kevin Anderson", slug: "kevin-anderson" }
        ]
      }
    }
  ) {
    id
    name
    author {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="connect">
```graphql
# Create a book and connect to an existing author
mutation createAndConnectOne {
  createBook(
    data: {
      name: "Rose madder"
      slug: "rose-madder"
      price: 30
      author: { connect: { slug: "stephen-king" } }
    }
  ) {
    id
    name
    author {
      name
    }
  }
}

# Create a book and connect to multiple existing authors
mutation createAndConnectMany {
  createBook(
    data: {
      name: "The road to Dune"
      slug: "the-road-to-dune"
      price: 30
      authors: {
        connect: [
          { slug: "frank-herbert" }
          { slug: "brian-herbert" }
          { slug: "kevin-anderson" }
        ]
      }
    }
  ) {
    id
    name
    author {
      name
    }
  }
}
```

  </TabsItem>
</Tabs>

## Migration best practices

Follow these guidelines to keep your migration predictable and recoverable:

- Plan the full migration before you start. Map your existing schema to Hygraph models and fields, and identify any transformations needed.
- Use the migration as an opportunity to improve your schema. Hygraph features like components can reduce duplication. Restructure where it makes sense.
- Migrate in dependency order. Assets must exist before content entries that reference them. Shared models must exist before models that connect to them.
- Prioritize critical content. Identify your most important content and migrate it first, before supporting or supplementary content.
- Avoid large, complex mutations. If a model connects to many other models, do not try to create and connect everything in a single mutation. Space requests out and stay within [rate limits](/docs/api-reference/basics/rate-limits).

## What's next

- [Management SDK](/docs/api-reference/management-sdk/management-sdk): Full reference for creating and updating schema elements programmatically.
- [Content API mutations](/docs/api-reference/content-api/mutations): Reference for create, update, connect, and nested mutations.
- [Upload assets](/docs/api-reference/assets/uploading-assets): Full documentation for asset uploads, including both legacy and current asset systems.
- [Rate limits](/docs/api-reference/basics/rate-limits): Understand request limits before running large-scale imports.
- [Field types](/docs/api-reference/schema/field-types): Reference for all field types available in Hygraph.

---
# Quickstart

Source: https://hygraph.com/docs/getting-started/quickstart

This Quickstart walks you through creating your first Hygraph project, from setup to querying content. If you’re looking for a deeper, end-to-end walkthrough, check out our [Full Tutorial: Build Your First eCommerce Project](/docs/getting-started/tutorial/tutorial-overview). It expands on these concepts with guided, step-by-step lessons that take you from project creation all the way to connecting a frontend.

## Register

1. You'll need a Hygraph account to get started. Go to <Link href="https://app.hygraph.com/signup" target="_blank">https://app.hygraph.com/signup</Link>.
2. Select one of the available options:
    - GitHub
    - Google
    - Email, password, and name
3. Select the checkbox to agree to the terms of service and privacy policy, and click **Continue**.
4. You'll receive a verification email. Click on the provided link and log in using your credentials.

After logging in, you'll land in your project directory. This is where you’ll find all your projects and create new ones. Any pending project invites are available at the top of the screen.

<Alert theme="info" title="Pro Tip">

If you’d like a quick overview of the Hygraph interface and navigation, see the [Studio walkthrough](/docs/getting-started/studio-walkthrough).

</Alert>

## Create a project

When you log in, you'll see a list of projects you own or have been invited to. If you’re new to Hygraph, this list may be empty.

You can either create a blank project or use our Showcase project to explore how Hygraph works. Click **Get started** to start exploring the Showcase project. Starting with the Showcase project helps you get a feel for how the platform works.

![First screen](/images/docs/getting-started/fundamentals/first-screen.png)

To add a blank project, follow these steps:

1. If you've just signed up, click **Start from scratch**. Otherwise, click **Add project**.
2. Select your plan. Choose Hobby, Enterprise, or start a 30-day trial. See our <Link href="https://hygraph.com/pricing" target="_blank">Pricing page</Link> for details.
3. Provide a project name, an optional description, and a content region. If you need a custom region, contact sales.
    - Hygraph stores your content in the region you select and delivers it globally via our CDN. Learn more in the [Caching](/docs/api-reference/basics/caching) documentation.
4. Click **Add project**. Hygraph redirects you to the project homepage.

    ![Blank new project](/images/docs/getting-started/fundamentals/new-project-blank.png)

## Create a model

Let's create a model for our products. Think of a model as a database table or collection in NoSQL that defines the schema and structure of your content.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkc6mce6w7w407vzxb6vyz2v" caption="Create a product model" />

1. Open the **Schema** builder.
2. Click **+ Add** and create a new model named `Product`, keeping the suggested API IDs.
3. Optionally add a description for editors and API users.
4. Click **Add Model**.

You’ve added a **Product** model to your GraphQL schema. With the model in place, you can now start adding fields.

## Add fields to your model

Fields define the data you can store on a model. Each field uses one of Hygraph’s supported [field types](/docs/api-reference/schema/field-types).

For this Quickstart, you'll add three fields to the `Product` model:
- `Name`
- `Price`
- `Image`

### Name field

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkc6s1powdqg07vz14auk5b2" caption="Create a name field" />

1. Select the **Single line text** field from the sidebar.
2. Set the **Display name** to **Name**.
3. Under **Validations**, enable **Make field required**.
4. Click **Add**.

### Price field

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkc70esywnnz07vztt4j5m2x" caption="Create a price field" />

1. Select the **Number** field from the sidebar.
2. Set the **Display name** to **Price**.
3. Under **Validations**, enable **Make field required**.
4. Click **Add**.

### Image field

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkc79pdhwzn707vzq23p0g4d" caption="Create an image field" />

1. Select the **Asset picker** field from the sidebar.
2. Set the **Display name** to **Image**.
3. Enable **Allow multiple assets**. This lets you add more than one image to each product entry.
4. Click **Add**.

Every project includes an **Asset** model by default. It is used to store images and other files. Learn more about [working with assets](/docs/developer-guides/assets/work-with-assets).

### System fields

Hygraph automatically manages [system fields](/docs/api-reference/schema/system-fields) such as `id`, `createdAt`, and `publishedAt`.

To view system fields, enable the **Show system fields** toggle in the **Fields** tab for your selected model.

![Show system fields](/images/docs/getting-started/fundamentals/show-system-fields-toggle.png)

## Create a content entry

With your schema ready, it’s time to add content.

![Add entry](/images/docs/getting-started/fundamentals/add-entry-button.png)

1. Navigate to the **Content** editor in your Hygraph project.
2. Under the **Default views** list, select the **Product** view. If your project only has the **Product** model so far, this view will display automatically when you access the content editor.
3. Your content entries table for **Product** is currently empty. To create content, click **+ Add entry** at the top-right corner of the screen.
4. Enter details for your new product. The available inputs correspond to the fields you added to the model.
   - Required and multi-value fields are enforced by the schema. Learn more about [field validations](/docs/api-reference/schema/field-configuration#validations).
    - `Name` and `Price` were set to **required** in the schema, so the UI here reflects those constraints.
5. Now, upload one or more images for your product. Click **Add image**, and upload an asset from your computer.
    - `Image` allows multiple images to be uploaded since we allowed **multiple values** in the schema.
6. Click **Save** to keep the entry in **DRAFT**.

![Entry in DRAFT stage](/images/docs/getting-started/fundamentals/entry-draft-stage.png)

## Publish your content

By default, all projects include the **DRAFT** and **PUBLISHED** [content stages](/docs/developer-guides/content/content-stages). Draft is commonly used for previews or staging environments, while Published represents live content. Publishing promotes an entry from **DRAFT** to **PUBLISHED** so it can be consumed via the API.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkdlaizgcv8a07ureiz3yc1q" caption="Publish your entry and assets" />

1. Click **Publish** at the top-right corner of the screen while editing your content entry to publish it. Once you click **Publish**, a confirmation modal displays. This modal will also include any related entries or assets that are currently in the **DRAFT** stage and may need publishing as well.
2. If you have unpublished referenced entries, select the **All entries** checkbox to include all related entries and assets in the **DRAFT** stage. Then, click **Publish**.
3. You can continue to make changes to your content entry, and then save it again as many times as you want without publishing. When you save but don't publish, it is marked as **outdated**. This means the published version differs from the latest draft in your Hygraph project.

    ![A blue Published pill indicates that the content entry is outdated](/images/docs/getting-started/fundamentals/outdated-content-entry.png)

4. You can repeat publishing outdated entries either by clicking the **Publish** button again, or by [scheduling for later](/docs/developer-guides/content/scheduled-publishing#how-to-schedule). Before saving changes you made to a content entry, the **Publish** button will read **Save & Publish** instead. Clicking **Save & Publish** saves and publishes the content at once, so make sure you only use it when the content is ready to go live.

    Check out the document on [content publishing](/docs/developer-guides/content/publishing-content) for more information.

## Query content

For every model that you create, Hygraph automatically generates GraphQL queries to fetch content entries. You can test these queries in the [API Playground](/docs/api-reference/basics/api-playground).

![The API Playground](/images/docs/getting-started/fundamentals/api-playground.png)

1. Navigate to the **API Playground** in your Hygraph project.
2. As you type `product` in the API Playground, you'll see recommended queries to fetch single or multiple product entries, an individual product version, and the [connection query](/docs/api-reference/content-api/queries#fetching-with-relay) to fetch edges/nodes.
3. Enter the following query:

    ```graphql
    {
      products {
        id
        name
        price
        image {
          url
          fileName
        }
      }
    }
    ```
4. Click the **Play** icon to run the query.

    - Since we enabled **Allow multiple assets** on the `image` field, the API will return our images within an array (denoted by `[]` in JSON), even if you upload only one image.
    - If you had unchecked **Allow multiple assets**  in the schema, the `image` field would return a single object `{}` instead of an array `[]`.

    ```json
    {
      "data": {
        "products": [
          {
            "id": "cmkcb1fu3itum07moq2f5pzjj",
            "name": "My product entry",
            "price": 2000,
            "image": [
              {
                "url": "https://eu-west-2.graphassets.com/cmk6vvkkl0dzk07mj5law3czs/cmkci63gk05hv07mmqaf80haj",
                "fileName": "t-shirt-white.jpg"
              }
            ]
          }
        ]
      }
    }
    ```

Explore the full [API Reference](/docs/api-reference) for additional information on filtering, pagination, ordering, and asset transformations.

<Alert theme="info" title="Are you new to GraphQL?">

Our [Full Tutorial: Build Your First eCommerce Project](/docs/getting-started/tutorial/tutorial-overview) offers the option to clone a project that you can use to practice queries.

</Alert>

## Mutate content

For every model that you create, Hygraph automatically generates GraphQL mutations so you can create, update, delete, publish, and unpublish content entries. You can try out all mutations in the [API Playground](/docs/api-reference/basics/api-playground).

1. Navigate to the **API Playground** in your Hygraph project.
2. In the API Playground, you'll start with the following:

    ```graphql
    mutation {

    }
    ```

3. Start typing `product` to see mutations for the `Product` model. For this example, we'll use the `updateProduct` mutation to modify the product entry we previously created using the UI.
    - Hover over the mutation to view its arguments and documentation.
    - Explore input types such as `ProductUpdateInput` to see available fields.

    ![updateProduct mutation](/images/docs/getting-started/fundamentals/update-product-mutation.png)

4. Use the `where` and `data` arguments to write the mutation. In this example, you’ll update the `price` field.
    - You'll need an `id` of the product you created previously to continue. You can copy it from the query results in the [Query content](#query-content) section.

    ```graphql
    mutation {
      updateProduct(where: { id: "<ADD_YOUR_ID_HERE>" }, data: { price: 25 }) {
        id
        name
        price
      }
    }
    ```

5. Click the **Play** icon to execute this mutation. The product entry is updated with the new `price` value.

<Alert theme="info" title="Are you new to GraphQL?">

Our [Full Tutorial: Build Your First eCommerce Project](/docs/getting-started/tutorial/tutorial-overview) offers the option to clone a project that you can use to practice mutations.

</Alert>

## API access

To access your content outside of Hygraph, you need to configure Content API permissions.

1. Navigate to **Project settings > Access > Content API**.
2. To create new permissions, click **Initialize defaults**. This sets `Read` permissions on all models on the **PUBLISHED** stage. This means that anyone can read published content via the Content API. You can also protect the API with [permanent auth tokens](/docs/api-reference/basics/authorization). Learn more in the [API access](/docs/getting-started/access-and-permissions/api-access) documentation.

    ![Content API permissions](/images/docs/getting-started/fundamentals/public-content-api-permissions.png)

3. Now that the API is public, let's test it. Go to **Project settings > Access > Endpoints**, and copy the **High Performance Content API** endpoint. This is the default Content API used for production reads.

    ![Content API URL](/images/docs/getting-started/fundamentals/content-api-url.png)

4. Paste this endpoint in your browser.

5. Run the query from the [Query content](/docs/getting-started/quickstart#query-content) section of this document. This is now publicly accessible on the web.
    - If you see any errors, verify that you've [published at least one `Product` content entry](#publish-your-content).

![Content publicly available](/images/docs/getting-started/fundamentals/content-publicly-available.png)

## Next steps

| Document                                                                      | About                                                                                                                                   |
|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| [Full Tutorial: Build Your First eCommerce Project](/docs/getting-started/tutorial/tutorial-overview) | Build a complete e-commerce project from schema design to a connected frontend.         |
| [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions) | Information on roles and permissions including system roles, custom roles, how to work with roles & permissions, and detailed examples. |

---
# Hygraph Studio walkthrough

Source: https://hygraph.com/docs/getting-started/studio-walkthrough

This page walks through the Hygraph Studio interface so you know where everything lives before you start building. If you want a step-by-step guide to creating a project and querying content, start with the [Quickstart](/docs/getting-started/quickstart).

## Overview

When you log in to your <Link href="https://app.hygraph.com" target="_blank">Hygraph account</Link>, you land in the project directory. This is the account-level view, separate from any individual project. Here you can find the following tabs at the top:
- **Projects**
- **Your apps**
- **Analytics**

### Projects

**Projects** lists your active projects and any pending project invites. It also includes a Showcase project you can use to explore Hygraph features before building your own.

![Projects](/images/docs/getting-started/fundamentals/projects-tab.png)

### Your apps

**Your apps** is where you create and manage custom apps you have built using the Hygraph App Framework. Apps you create here can be installed into projects and shared with other users.

![Your apps](/images/docs/getting-started/fundamentals/project-directory-apps-tab.png)

### Analytics

**Analytics** gives you a usage overview across all projects you have access to, scoped to the `master` environment. You can customize which projects appear in the list and which columns are shown, including plan, API calls, asset traffic, content entries, locales, and seats.

You can perform the following tasks on this dashboard:
- Click **Open** next to the project name to access the project.
- Select **Adjust columns** to customize which columns you want to display. The following columns are available:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - Owner of the project
        - Plan
        - Region
        - Billing period
        - API calls
        - Asset traffic
        - Content models
      </div>
      <div className="flex-1">
        - Components
        - Remote sources
        - Taxonomies
        - Content entries
        - Locales
        - Seats
        - Workflows
      </div>
    </div>

![Analytics](/images/docs/getting-started/fundamentals/project-analytics.png)

## Project sidebar

Once you open a project, the left sidebar is your primary navigation. It contains the following sections.

![Hygraph Studio sidebar](/images/docs/getting-started/fundamentals/project-dashboard.png)

### Home

The project homepage. It surfaces recently updated schema elements, links to documentation, and video content.

### Schema

The Schema builder is where you define the structure of your content. You create models, add fields, configure relationships, set up components, and connect remote sources here. 

| Action | Description |
|---|---|
| [Create a model](/docs/getting-started/quickstart#create-a-model) | Define a new content model and add fields to it. |
| [Add fields to a model](/docs/getting-started/quickstart#add-fields-to-your-model) | Extend an existing model with new field types. |
| [Add components](/docs/developer-guides/schema/components) | Create reusable field templates that can be embedded in multiple models. |
| [Add remote sources](/docs/developer-guides/remote-data/remote-sources) | Connect external APIs so their content is queryable through the Hygraph API. |
| [Add enumerations](/docs/developer-guides/schema/using-enumerations) | Define a fixed list of values for use in dropdown fields. |
| [Customize the content entry sidebar](/docs/developer-guides/content/customize-sidebar) | Add or remove widgets from the content entry sidebar. |

### Content

The Content editor is where you create, edit, review, and publish entries based on the models in your schema. It supports default and custom views, so you can organize your content workspace to match your editorial workflow.

| Action | Description |
|---|---|
| [Create a content entry](/docs/getting-started/quickstart#create-a-content-entry) | Add a new entry based on an existing model. |
| [Publish content](/docs/getting-started/quickstart#publish-your-content) | Make an entry available via the Content API for the `PUBLISHED` stage. |
| [Update content](/docs/developer-guides/content/updating-content) | Edit an existing entry, whether published or in draft. |
| [Duplicate content](/docs/developer-guides/content/duplicating-content) | Copy an entry to use as the basis for a new one. |
| [Schedule publishing](/docs/developer-guides/content/scheduled-publishing) | Set a future date and time for an entry to publish or unpublish. |
| [Delete content](/docs/developer-guides/content/deleting-content) | Remove entries individually or in bulk. |
| [Access content views](/docs/developer-guides/content/access-created-content) | Navigate to and customize how your content list is displayed. |

### Assets

The Assets manager is where you upload and store files used in content entries. Like the Content editor, it supports default and custom views.

| Action | Description |
|---|---|
| [Add an asset entry](/docs/developer-guides/assets/add-asset-entry) | Upload a file and add metadata to it. |
| [Upload assets](/docs/developer-guides/assets/upload-asset) | Bring files in from different sources. |
| [Work with assets](/docs/developer-guides/assets/work-with-assets) | Manage your asset table, similar to working with content entries. |

### AI Hub

AI Hub contains Hygraph's AI-related tooling for your project, including AI agents and Guidelines. It is distinct from **AI Assist**, which is the top-bar tool for generating and improving content inline within the Content editor.

| Action | Description |
|---|---|
| [AI agents](/docs/hygraph-ai/ai-agents) | Create and manage AI agents for your project. |
| [AI guidelines](/docs/hygraph-ai/ai-guidelines) | Create and manage AI guidelines for your project. |

### API Playground

The API Playground lets you test queries and mutations against your project's API directly in Studio. Use it to verify that your schema is returning the data you expect before wiring up a frontend.

| Action | Description |
|---|---|
| [Test queries](/docs/api-reference/content-api/queries) | Run GraphQL queries against your content API. |
| [Test mutations](/docs/api-reference/content-api/mutations) | Create, update, or delete content via the API to verify behavior. |

### Apps

The **Apps** section shows the apps installed in your current project environment. From here you can configure or uninstall them, or go to the <Link href="https://hygraph.com/marketplace" target="_blank">Marketplace</Link> to browse and install more. This is different from the **Your apps** tab in the project directory, where you create and manage apps you have built yourself.

| Action | Description |
|---|---|
| [Install apps](/docs/integrations) | Browse and install apps from the <Link href="https://hygraph.com/marketplace/apps" target="_blank">Marketplace</Link>. |

### Project Settings

Project Settings is where you manage everything that applies to the project as a whole: API access, environments, locales, roles, billing, and team members.

| Action | Description |
|---|---|
| [Manage project information](/docs/developer-guides/project/manage-project-info) | Edit project details, clone your project, enable public cloning, manage support access, leave the project, or delete it. |
| [Manage environments](/docs/developer-guides/project/manage-project-environments) | Create and switch between isolated instances of your project. |
| [Manage API access](/docs/getting-started/access-and-permissions/api-access) | Configure endpoints, content API permissions, and permanent auth tokens. |
| [Configure webhooks](/docs/developer-guides/webhooks/webhooks-overview) | Set up webhooks to trigger external actions on content events. |
| [Manage roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions) | Control what different team members can see and do in your project. |
| [Manage team members](/docs/getting-started/access-and-permissions/manage-team-members) | Add members and assign roles. |
| [Manage locales](/docs/developer-guides/project/manage-project-locales) | Add languages to support localized content. |
| [Manage content stages](/docs/developer-guides/content/content-stages) | Create custom workflow stages beyond Draft and Published. |
| [Manage audit logs](/docs/developer-guides/project/audit-logs) | Review a full history of schema and content changes in your project. |
| [Update billing](/docs/getting-started/update-billing) | Change your plan or update payment information. |
| [Clone your project](/docs/developer-guides/project/clone-your-project) | Create a copy of your project's master environment. |
| [Share your project](/docs/developer-guides/project/share-your-project) | Generate a public clone link for others to copy your project. |

## Top bar

The top bar is visible across all project sections. It gives you access to account-level tools and contextual actions.

![Hygraph Studio top bar](/images/docs/getting-started/fundamentals/top-bar.png)

| Item | What you can do |
|---|---|
| Project and environment | See the current project and environment. Use the dropdown to switch projects or environments. |
| Trial indicator | View your current plan. Click to open the plan picker and upgrade. |
| Search | Find content entries across your environment. |
| Recently viewed | Return to entries you viewed recently. |
| AI Assist | Generate, improve, and localize content inline within the content entry editor. Available on enabled projects only. |
| Help | Access documentation, code examples, and the Hygraph Slack community. |
| Contact Support | Reach the Hygraph support team. |
| Notifications | View alerts and updates across all your Hygraph projects. Unread notifications show a red indicator on the bell icon. |
| Profile | Access your account settings or log out. |

## What's next

- [Quickstart](/docs/getting-started/quickstart): Create a project, define a schema, and query your first content entry.
- [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview): Start building a full project in Hygraph, from schema to frontend.

---
# Lesson 4.2 - Add components to your models

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-add-components-to-models

In this lesson, you will attach the components built in lesson 4.1 to the `Product`, `Landing page`, and `Navigation` models. After this lesson, the schema is structurally complete.

## Product

The `Product` model receives two component fields: `Product Variant` and `Related Products` as basic component fields. Both are basic because each field always contains a single, fixed component type — there is no editorial choice about which component fills the field.

1. In the Schema editor, open the `Product` model.
2. From the right sidebar, add a **Basic** component field with the following information, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display Name | Product Variant |
    | API ID | ProductVariant |
    | Select component | Product Variant |

3. Add a second **Basic** component field with the following information, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display Name | Related Products |
    | API ID | RelatedProduct |
    | Description | Add related products |
    | Select component | Related Products |

Your Product model should now look like this:

![Finished Product model with fields](/images/docs/getting-started/product-model.png)

## Landing page

The `Landing page` model receives a modular component field called `Stripes`. It is modular because editors need to choose which component fills each section, either a `Call to Action` or a `Product Grid`. Allowing multiple values means editors can add as many sections as needed, in any order.

1. In the Schema editor, open the **Landing page** model.
2. From the right sidebar, add a **Modular** component field with the following information, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display Name | Stripes |
    | API ID | stripes |
    | Description | Sections |
    | Allow multiple values | Select checkbox |
    | Select allowed components | Call to Action, Product Grid |

Your Landing page model should now look like this:

![Finished Landing Page model with fields](/images/docs/getting-started/landing-page-model.png)

## Navigation

The Navigation model was left incomplete in lesson 1.2. It has a Nav ID field but no way to hold navigation links. The Link component built in lesson 4.1 is what completes it.

1. In the Schema editor, open the **Navigation** model.
2. From the right sidebar, add a **Basic** component field with the following information, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display Name | Nav Link |
    | API ID | navLink |
    | Description | Navigation links |
    | Allow multiple values | Select checkbox |
    | Select component | Link |

The **Allow multiple values** setting is what enables the navigation to hold multiple links. Each link added in the content editor is a separate instance of the Link component.

Your `Navigation` model should now look like this:

![Finished Navigation model](/images/docs/getting-started/navigation-model.png)

Every model has the fields, references, and component fields it needs. 

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-remote-sources-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 5 - Remote Sources</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 5.2 - Add remote fields

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-add-remote-fields

In this lesson, you will add a remote field to the `Product` model. Remote fields fetch data from a remote source in the context of a specific model entry. The field uses a value from the entry itself, in this case `productSlug`, as the argument passed to the external API, so the reviews returned are always scoped to that product.

This is different from a top-level remote field, which fetches remote data independently of any entry. That is covered in lesson 5.3.

## Add a remote field to the Product model

You will use the `HyDemoAPI` remote source configured in lesson 5.1 to add a `Reviews` field to the **Product** model.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/mDIeXmgzQ0yis5Uv7drY" caption="Add a remote field to the Product model" />

1. Open the **Product** model in the Schema editor and from the right sidebar, add a **REST** remote field.
2. Fill in the following information:

    | Field | Input |
    |---|---|
    | Display name | Reviews |
    | API ID | Auto-completed. Leave as is. |
    | Remote source | HyDemoAPI is selected by default. Leave as is. |
    | Method | GET is selected by default. Leave as is. |
    | Return type | Select `Reviews` from the dropdown |
    | Path | `/api/reviews/product/{{doc.productSlug}}` |

    The `Path` appends to the remote source base URL. `{{doc.productSlug}}` references the `productSlug` field on the current `Product` entry, which scopes the review data to that specific product.

3. Click **Add** to save.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-add-top-level-remote-fields"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 5.3 - Add top-level remote fields</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 5.1 - Add a remote source

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-add-remote-source

In this lesson, you will add a remote source to the project schema. Before this step, the schema only returns data stored in Hygraph. After it, the schema includes queryable types from an external REST API that can be fetched alongside Hygraph content.

A remote source is a custom resolver entry point in the schema. It accepts field values from other Hygraph fields as arguments, which is what makes it possible to fetch reviews scoped to a specific product in lesson 5.2.

## Configure the remote source

You will connect a REST API using the Hygraph demo API.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9whe6htpu07vxptrtlej3" caption="Configuring the remote source" />

1. Navigate to the **Schema editor** and click **+Add** next to **Remote Sources**.
2. Fill in the following information:

    | Field | Input |
    |---|---|
    | Select remote source type | Custom source |
    | Display Name | HyDemoAPI |
    | Type | REST |
    | Base URL | `https://demo-api.hygraph.workers.dev` |

    The base URL is the root endpoint for all remote fields that use this source. Individual remote fields append their own paths to this base.

3. Click **Add** to save the remote source configuration before adding type definitions.

## Add custom type definitions

REST APIs return fixed data structures. To query a REST API as if it were native GraphQL, Hygraph needs to know the shape of the data it will receive. Custom type definitions provide that shape using GraphQL SDL.

<Alert theme="info" title="What is SDL?">
SDL stands for Schema Definition Language. It is the syntax used to define types and their fields in a GraphQL schema. The type definitions added here describe the structure of the data the `HyDemoAPI` returns, so Hygraph can expose those types in the project's GraphQL schema.
</Alert>

1. For each type definition, click **+Add custom type definition** and paste the snippets:

    <Tabs panelHeight={280}>
      <TabsItem label="Review">

    ```GraphQL
    type Review {
      id: Int
      name: String
      product: String
      rating: Float
      comment: String
    }
    ```

      </TabsItem>
      <TabsItem label="Reviews">

    ```GraphQL
    type Reviews {
      data: [Review]
    }
    ```

      </TabsItem>
    </Tabs>

2. Click **Add Remote Source** to save the configuration.

Your finished remote source should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8mehu3j07vx7uzhl9ex" caption="Finished remote source" />

The `Reviews` type wraps a list of `Review` entries. These two types are used by the remote fields in lessons 5.2 and 5.3.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-add-remote-fields"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 5.2 - Add remote fields</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 5.3 - Add top-level remote fields

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-add-top-level-remote-fields

In this lesson, you will add a top-level remote field to the **Query** system model and run a test query to confirm the remote source is working correctly.

A top-level remote field fetches remote data outside the context of any model entry. Where the remote field added in lesson 5.2 only returns reviews for a specific product, a top-level remote field can return review data independently. This is useful for fetching all reviews, or for passing in an argument from the frontend rather than from a content entry.

## Add a top-level remote field

You will add the field to the **Query** system model using the same `HyDemoAPI` remote source.

![Complete top-level remote field configuration](/images/docs/getting-started/top-level-remote-field.png)

1. Open the **Query** model in the Schema editor and from the right sidebar, add a **REST** remote field.
2. Fill in the following information:

    | Field | Input |
    |---|---|
    | Display name | Reviews |
    | API ID | Auto-completed. Leave as is. |
    | Remote source | HyDemoAPI is selected by default. Leave as is. |
    | Method | GET is selected by default. Leave as is. |
    | Return type | Select `Reviews` from the dropdown |
    | Input arguments | Click **+ Add input argument** to reveal the argument fields |
    | Input type | String |
    | API ID | productSlug |
    | Make field required | Select checkbox |
    | Path | `/api/reviews/product/{{args.productSlug}}` |

    The `Path` appends to the remote source base URL. The `{{args.productSlug}}` path argument is supplied by whoever runs the query: a frontend component, a developer testing in the API Playground, or any API client. This means the top-level remote field has no dependency on Hygraph content. It can be queried even if the `Product` model contains no entries at all.

    The remote field in [lesson 5.2](/docs/getting-started/tutorial/tutorial-add-remote-fields#add-a-remote-field-to-the-product-model) works differently. Its path uses `{{doc.productSlug}}`, which pulls the `productSlug` value from the specific `Product` entry being queried. The top-level remote field removes that dependency entirely.

3. Click **Add** to save.

## Test the top-level remote field

Because the top-level remote field is not connected to a content entry, it can be tested immediately without creating any content first.

1. Navigate to the **API Playground**.
2. Run the following query:

    <Tabs panelHeight={300}>
      <TabsItem label="Query">

    ```graphql
    query MyQuery {
      reviews(productSlug: "plaid-shirt") {
        data {
          comment
          id
          name
          product
          rating
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Response">

    ```json
    {
      "data": {
        "reviews": {
          "data": [
            {
              "comment": "After wearing this shirt for 2 days, I realized it was made of cotton. I am allergic to cotton.",
              "id": 3,
              "name": "Oregon Person",
              "product": "plaid-shirt",
              "rating": 1.5
            },
            {
              "comment": "This shirt is okay. It lost a button, but I sewed it back on.",
              "id": 6,
              "name": "Another Person",
              "product": "plaid-shirt",
              "rating": 3.5
            },
            {
              "comment": "I love this shirt. I wear it all the time.",
              "id": 7,
              "name": "Third Person",
              "product": "plaid-shirt",
              "rating": 4.5
            }
          ]
        }
      }
    }
    ```

      </TabsItem>
    </Tabs>

The response confirms the remote source is correctly configured. The Hygraph API returns external review data without any data migration and without a separate API call from the frontend. This is [Content Federation](/docs/core-concepts/content-federation) working as intended.

The schema is now complete. Content creation starts in the next lesson.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-content-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 6 - Content</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 4.1 - Build components

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-build-components

In this lesson, you will build all components the project needs. These components must exist before you can attach them to models in [Lesson 4.2](/docs/getting-started/tutorial/tutorial-add-components-to-models).

<Alert theme="info" title="Build order matters">
Some components depend on others. Build them in the order they appear in this lesson. `Clothing`, `Shoes`, `Accessories`, and `Decor` must exist before `Product Variant`. `Button` must exist before `Call to Action`. 
</Alert>

## Related Products

The `Related Products` component enables product pages to display other products a buyer might be interested in. It contains a read-only title field and a reference field that connects to other `Product` entries.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/ixrjl62AQu9OVv2kOaHB" caption="Add Related Products component field" />

1. In the Schema editor, click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Related Products |
    | API ID | RelatedProduct |
    | Plural API ID | RelatedProducts |

3. Add the following fields to the `Related Products` component:

    **Single line text** - `Title`:

    | Field | Input |
    |---|---|
    | Display name | Title |
    | Use as title field | Select checkbox |
    | Make field required | Select checkbox |
    | Set initial value | Select checkbox, and enter `Related Products` in the initial value field |
    | Field visibility | Read only |

    The read-only title with an initial value ensures every instance of this component displays the same heading without editors being able to change it.

    **Reference** - `Products`:

    | Field | Input |
    |---|---|
    | Reference type | Allow only one model to be referenced |
    | Model to reference | Product |
    | Reference directions | One-way reference |
    | Allow multiple Products per RelatedProduct | Select checkbox |
    | Display name | Products |
    | API ID | products |
    | Description | Add 4 related products here |
    | Field visibility | Read / Write |

4. Click **Add** to save.

Your `Related Products` component should look like this:

![Related Products component](/images/docs/getting-started/related-products-component.png)

## Product type components

The store sells four product types: clothing, shoes, accessories, and decor. Each type requires different fields. Rather than creating four separate `Product` models, you will use four components, one per product type, and nest them inside a modular `Product Variant` component. The content editor then presents only the fields relevant to the selected product type.

These four components use the enumerations created in [Lesson 3.1](/docs/getting-started/tutorial/tutorial-configure-enumerations).

### Clothing

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Clothing |
    | API ID | Clothing |
    | Plural API ID | ClothingItems |

3. Add the following fields:

    **Enumeration** - `Size`:

    | Field | Input |
    |---|---|
    | Display name | Size |
    | API ID | Auto-completed. Leave as is. |
    | Enumeration | Clothes size |
    | Make field required | Select checkbox |

    **Enumeration** - `Color`:

    | Field | Input |
    |---|---|
    | Display name | Color |
    | Enumeration | Wearable items color |
    | Make field required | Select checkbox |

Your Clothing component should look like this:

![Clothing component](/images/docs/getting-started/clothing-component.png)

### Shoes

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Shoes |
    | API ID | Shoe |
    | Plural API ID | Shoes |

3. Add the following fields:

    **Enumeration** - `Size`:

    | Field | Input |
    |---|---|
    | Display name | Size |
    | Enumeration | Shoes size |
    | Make field required | Select checkbox |

    **Enumeration** - `Color`:

    | Field | Input |
    |---|---|
    | Display name | Color |
    | Enumeration | Wearable items color |
    | Make field required | Select checkbox |

Your Shoes component should look like this:

![Shoes component](/images/docs/getting-started/shoes-component.png)

### Accessories

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Accessories |
    | API ID | Accessory |
    | Plural API ID | Accessories |

3. Add the following field:

    **Enumeration** - `Color`:

    | Field | Input |
    |---|---|
    | Display name | Color |
    | Enumeration | Wearable items color |
    | Make field required | Select checkbox |

Your Accessories component should look like this:

![Accessories component](/images/docs/getting-started/accessories-component.png)

### Decor

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Decor |
    | API ID | Decor |
    | Plural API ID | DecorItems |

3. Add the following field:

    **Enumeration** - `Color`:

    | Field | Input |
    |---|---|
    | Display name | Color |
    | Enumeration | Decor items color |
    | Make field required | Select checkbox |

Your Decor component should look like this:

![Decor component](/images/docs/getting-started/decor-component.png)

## Product Variant

The `Product Variant` component contains a modular component field that presents `Clothing`, `Shoes`, `Accessories`, or `Decor` based on the product type an editor selects. This is the component that makes a single `Product` model work for all four product types.

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Product Variant |
    | API ID | ProductVariant |
    | Plural API ID | ProductVariants |

3. Add the following field:

    **Modular component** - `Product type`:

    | Field | Input |
    |---|---|
    | Display name | Product type |
    | API ID | productType |
    | Description | Select the product type to reveal fields |
    | Select allowed components | Clothing, Shoes, Accessories, Decor |

4. Click **Add** to save.

Your Product Variant component should look like this:

![Product Variant component](/images/docs/getting-started/product-variant-component.png)

## Button

The `Button` component holds a text label and a URL. It is used inside the `Call to Action` component in the next step.

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display Name | Button | 
    | API ID | Button | 
    | Plural API ID | Buttons | 

3. Add the following fields:

    **Single line text** - `Text`:

    | Field | Input |
    |---|---|
    | Display name | Text |
    | Localize field | Select checkbox |

    **Slug** - `URL`:

    | Field | Input |
    |---|---|
    | Display name | URL |
    | Match a specific pattern | Select checkbox, then select `URL` from the dropdown |
    | Custom error message | Input value does not match the expected format. |

Your `Button` component should look like this:

![Button component](/images/docs/getting-started/button-component.png)

## Call to Action

The `Call to Action` component is used as a page section on Landing pages. It embeds the `Button` component created in the previous step.

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Call to Action |
    | API ID | CallToAction |
    | Plural API ID | CallToActions |

3. Add the following fields:

    **Single line text** - `Heading`:

    | Field | Input |
    |---|---|
    | Display name | Heading |
    | Localize field | Select checkbox |

    **Rich Text** - `Body`:

    | Field | Input |
    |---|---|
    | Display name | Body |
    | Localize field | Select checkbox |

    **Asset picker** - `Image`:

    | Field | Input |
    |---|---|
    | Display name | Image |

    **Basic component** - `Button`:

    | Field | Input |
    |---|---|
    | Display name | Button |
    | Select component | Button |

Your `Call to Action` component should look like this:

![CTA component](/images/docs/getting-started/cta-component.png)

## Product Grid

The `Product Grid` component is used as a page section on Landing pages. It displays a headline, a description, and a set of `Product` references.

1. Click **+Add** next to **Components**.
2. Provide the following information, and click **Add Component** to save:

    | Field | Input |
    |---|---|
    | Display Name | Product Grid |
    | API ID | ProductGrid |
    | Plural API ID | ProductGrids |

3. Add the following fields:

    **Single line text** - `Headline`:

    | Field | Input |
    |---|---|
    | Display name | Headline |
    | Localize field | Select checkbox |

    **Rich Text** - `Description`:

    | Field | Input |
    |---|---|
    | Display name | Description |

    **Reference** - `Products`:

    | Field | Input |
    |---|---|
    | Reference type | Allow only one model to be referenced |
    | Model to reference | Product |
    | Reference directions | One-way reference |
    | Allow multiple Products per ProductGrid | Select checkbox |
    | Display name | Products |
    | API ID | products |
    | Field visibility | Read / Write |

Your `Product Grid` component should look like this:

![Product Grid component](/images/docs/getting-started/product-grid-component.png)

## Link component

The `Link` component is included in the cloned project. It already contains two fields: `Display text` and `External URL`. You need to add a `Reference` field to it that connects it to the `Blog post`, `Landing page`, and `Product` models. This reference field could not be included in the original clone because it references models that did not exist until lesson 1.2.

**This is the same layered schema pattern seen in lesson 1.2.** Models and components are built in layers because some connections can only be made after the things they connect exist.

1. In the Schema editor, under the **Components** section, select the **Link** component from the left sidebar.
2. From the right sidebar, add a **Reference** field with the following information:

    | Field | Input |
    |---|---|
    | Reference type | Allow multiple models to be referenced |
    | Model to reference | Blog post, Landing page, Product |
    | Reference directions | One-way reference |
    | Relation cardinality | To one |
    | Display name | Page |
    | API ID | page |
    | Field visibility | Read / Write |

3. Click **Add** to save.

Your finished Link component should look like this:

![Link component](/images/docs/getting-started/link-component-finished.png)

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-add-components-to-models"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 4.2 - Add components to your models</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 1.2 - Build your content models

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-build-content-models

In this lesson, you will create the base content models for the e-commerce project. These models are intentionally incomplete at this stage. References, components, and remote fields are added in later lessons.

<Alert theme="warning">
Every Hygraph project includes two system models: **Asset** and **Query**. These cannot be deleted, but you can add fields to them. The **Asset** model stores images. The **Query** model is where top-level remote fields are configured. You can create models to determine the structure of your content. You can create, rename, edit, and delete them.
</Alert>

## Asset model

Before creating models, you need to add two fields to the **Asset** model. Product images require alt text and captions. Both fields are localized, so translated values can be added when Spanish localization is configured in lesson 6.2.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9whh8jaen07w505t6k2ux" caption="Asset model - Alt text" />

1. In your Hygraph project, click **Schema**, and then under **Models**, click **Asset**.
2. In the right sidebar, click **+Add** next to **Single line text**. Provide the following information, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display name | Alt text |
    | API ID | altText |
    | Description | Add alternative text for the image here |
    | Localize field | Select checkbox |

3. Add a second `Single line text` field for the caption, and click **Add** to save:

    | Field | Input |
    |---|---|
    | Display name | Caption |
    | API ID | caption |
    | Description | Add image caption here |
    | Localize field | Select checkbox |

Your Asset model should look like this:

![Your Asset model](/images/docs/getting-started/asset-model.png)

## Product

The `Product` model holds information for product listings. 

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/guE2faIRSFaUXdj2AflT" caption="Add fields to Product model" />

To create the `Product` model, follow these steps:

1. Click **+Add** next to **Models**.
2. Provide the following information, and click **Add Model** to save:

    | Field | Input |
    |---|---|
    | Display name | Product |
    | API ID | Product |
    | Plural API ID | Products |
    | Description | Tutorial project Product model |


3. Add the following fields to the `Product` model:

    **Single line text** - `Product name`:

    | Field | Input |
    |---|---|
    | Display name | Product name |
    | API ID | Auto-completed. Leave as is. |
    | Use as title field | Select checkbox |
    | Localize field | Select checkbox |
    | Make field required | Select checkbox |
    | Set field as unique | Select checkbox |

    <Alert theme="info" title="API IDs">
    Each API ID is a unique identifier across the project. The system will not allow duplicates. Display names do not have this restriction, but keeping them descriptive helps collaborators navigate the schema.
    </Alert>

    **Slug** - `Product Slug`:

    | Field | Input |
    |---|---|
    | Display name | Product Slug |
    | API ID | Auto-completed. Leave as is. |
    | Lowercase | Leave selected |
    | Make field required | Select checkbox |
    | Set field as unique | Select checkbox |
    | Match a specific pattern | Select checkbox, then select `Slug` from the dropdown |
    | Custom error message | Input value does not match the expected format. |

    **Asset picker** - `Product image`: 

    | Field | Input |
    |---|---|
    | Display name | Product image |
    | Allow multiple assets | Select checkbox |

    **Rich Text** - `Product description`:

    | Field | Input |
    |---|---|
    | Display name | Product description |
    | API ID | Auto-completed. Leave as is. |
    | Enable embedding | Select checkbox. Select the **Asset** and **Product** models from the dropdown. |
    | Localize field | Select checkbox |

    **Enabling embedding on the Product description field** allows editors to embed images and product entries directly in the description body. The Product category model does not exist yet, so you will add it after creating that model.

    **Float** - `Product price`:

    | Field | Input |
    |---|---|
    | Display name | Product price |
    | API ID | Auto-completed. Leave as is. |

Your Product model should look like this:

![Your Product model so far](/images/docs/getting-started/product-model-initial-fields.png)

This model is not finished. A product variant component is added in lesson 4 and a reviews remote field in lesson 5.

## Product category

The `Product category` model holds categories that products are assigned to. It connects to the `Product` model through a reference, which we configure in lesson 2.

To create the `Product category` model, follow these steps:

1. Click **+Add** next to **Models**.
2. Provide the following information, and click **Add Model** to save:

    | Field | Input |
    |---|---|
    | Display Name | Product category |
    | API ID | ProductCategory |
    | Plural API ID | ProductCategories |
    | Description | Select a product category |

3. Add the following fields to the `Product category` model:

    **Single line text** - `Category name`:

    | Field | Input |
    |---|---|
    | Display name | Category name |
    | Use as title field | Select checkbox |
    | Localize field | Select checkbox |
    | Make field required | Select checkbox |
    | Set field as unique | Select checkbox |

    **Slug** - `Slug`:

    | Field | Input |
    |---|---|
    | Display name | Slug |
    | Lowercase | Leave selected |
    | Make field required | Select checkbox |
    | Set field as unique | Select checkbox |
    | Match a specific pattern | Select checkbox |
    | Custom error message | Input value does not match the expected format. |

    **Rich Text** - `Description`:

    | Field | Input |
    |---|---|
    | Display name | Description |
    | Localize field | Select checkbox |

Your `Product category` model should look like this:

![Your Product category model so far](/images/docs/getting-started/product-category-model-fields.png)

Now return to the `Product` model and edit the `Product description` Rich Text field. Add **Product category** to the **Enable embedding** dropdown.

![Product category in Rich Text embeds](/images/docs/getting-started/product-category-rich-text.png)

**Schema building is not always linear.** Models are interconnected, and you will sometimes need to return to an earlier model after creating a later one. This is expected.

## Blog post

The Blog post model holds articles that promote products.

To create the `Blog Post` model, follow these steps:

1. Click **+Add** next to **Models**.
2. Provide the following information, and click **Add Model** to save:

    | Field | Input |
    |---|---|
    | Display Name | Blog Post |
    | API ID | BlogPost |
    | Plural API ID | BlogPosts |
    | Description | Articles to promote our products |

3. Add the following fields to the `Blog Post` model:

    **Single line text** - `Title`:

    | Field | Input |
    |---|---|
    | Display name | Title |
    | Use as title field | Select checkbox |
    | Localize field | Select checkbox |
    | Make field required | Select checkbox |
    | Set field as unique | Select checkbox |

    **Slug** - `Slug`:

    | Field | Input |
    |---|---|
    | Display name | Slug |
    | Generate slug from template | Select checkbox |
    | Slug template | `{title}` |
    | Lowercase | Select checkbox |
    | Match a specific pattern | Select checkbox, then select `Slug` from the dropdown |
    | Custom error message | Input value does not match the expected format. |

    **Rich Text** - `Body`:

    | Field | Input |
    |---|---|
    | Display name | Body |
    | Localize field | Select checkbox |
    | Enable embedding | Select checkbox. Select **Blog Post**, **Product**, and **Product category** from the dropdown. |

Your Blog post model should look like this:

![Blog post model fields](/images/docs/getting-started/blog-post-model-fields.png)

## Seller information

The Seller information model holds business details referenced from the landing page.

To create the `Seller information` model, follow these steps:

1. Click **+Add** next to **Models**.
2. Provide the following information, and click **Add Model** to save:

    | Field | Input |
    |---|---|
    | Display Name | Seller information |
    | API ID | SellerInformation |
    | Plural API ID | SellerInformations |

3. Add the following fields to the `Seller information` model:

    **Single line text** - `Business name`:

    | Field | Input |
    |---|---|
    | Display name | Business name |
    | Use as title field | Select checkbox |
    | Localize field | Select checkbox |
    | Make field required | Select checkbox |

    **Slug** - `Slug`:

    | Field | Input |
    |---|---|
    | Display name | Slug |
    | Lowercase | Leave selected |
    | Make field required | Select checkbox |
    | Set field as unique | Select checkbox |
    | Match a specific pattern | Select checkbox, then select `Slug` |
    | Custom error message | Input value does not match the expected format. |

    **Asset picker** - `Business logo`:

    | Field | Input |
    |---|---|
    | Display name | Business logo |

    **Rich Text** - `Business description`:

    | Field | Input |
    |---|---|
    | Display name | Business description |
    | API ID | Auto-completed. Leave as is. |
    | Localize field | Select checkbox |

## Landing page

The Landing page model supports flexible page structures. It is intentionally minimal at this stage. Component fields and references are added in lessons 2 and 4.

1. Click **+Add** next to **Models**.
2. Provide the following information, and click **Add Model** to save:

    | Field | Input |
    |---|---|
    | Display Name | Landing page |
    | API ID | LandingPage |
    | Plural API ID | LandingPages |

3. Add the following fields to the `Landing page` model:

    **Single line text** - `Landing page title`:

    | Field | Input |
    |---|---|
    | Display name | Landing page title |
    | Use as title field | Select checkbox |
    | Localize field | Select checkbox |

    **Slug** - `Link`:

    | Field | Input |
    |---|---|
    | Display name | Link |
    | API ID | Auto-completed. Leave as is. |
    | Generate slug from template | Select checkbox |
    | Slug template | `{landingPageTitle}` |
    | Lowercase | Leave selected |
    | Set field as unique | Select checkbox |
    | Match a specific pattern | Select checkbox. Select **Custom** and enter: `^[a-z0-9\/]+(?:[-\/][a-z0-9]+)*$` |
    | Custom error message | Input value does not match the expected format. |

## Navigation

The Navigation model is included in the cloned project. At this stage it contains the `Nav ID` field, which is a slug field used as the navigation identifier. This model is incomplete. A way to hold navigation links is added in lesson 4.2 after creating the Link component.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-references-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 2 - References</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 4 - Components

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-components-overview

This section covers building the components the e-commerce project needs and attaching them to the correct models.

A component is a reusable set of fields defined once in the schema and embedded in models as a basic or modular component field. The components built here solve two specific problems in this project. The `Product Variant` modular component makes it possible for a single `Product` model to handle clothing, shoes, accessories, and decor, each with its own required fields, without creating four separate models. The `Stripes` modular component on the `Landing page` model gives editors the ability to compose pages from a variable combination of CTA and Product Grid sections.

By the end of lesson 4.2, the following models are updated:

- `Product` — `Product Variant` and `Related Products` components attached
- `Landing page` — `Stripes` modular component attached
- `Navigation` — `Nav Link` component attached, completing the model left open in lesson 1.2

## Components and component fields

A component and a component field are two different things. You create the component first, then embed it in a model using a component field.

Hygraph supports two types of component fields:

| Type | What it does |
|---|---|
| Basic component field | Embeds a single component type. Use this when the field always contains the same structure. |
| Modular component field | Allows editors to choose from a set of component types. Use this when editors need to select which component fills the field. |

The product type components (`Clothing`, `Shoes`, `Accessories`, `Decor`) use a modular component field inside `Product Variant` because the content editor needs to present a choice. The `Related Products` component uses a basic component field because no choice is required. It always contains the same structure.

## Build order matters

Some components depend on others. Build them in this order:

1. Related Products
2. Clothing, Shoes, Accessories, Decor (in any order)
3. Product Variant (depends on 2)
4. Button
5. Call to Action (depends on 4)
6. Product Grid
7. Link component modification (pre-built in the cloned project)

For the complete components documentation, see [Components](/docs/developer-guides/schema/components).

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [4.1 Build components](/docs/getting-started/tutorial/tutorial-build-components) | Create components and configure their fields, references, and nested component fields |
| [4.2 Add components to your models](/docs/getting-started/tutorial/tutorial-add-components-to-models) | Attach the components to the `Product`, `Landing page`, and `Navigation` models to complete the schema |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-build-components"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 4.1 - Build components</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 3.1 - Configure enumerations

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-configure-enumerations

In this lesson, you will create enumerations for product size and color values that the product variant components will use. These must exist in the schema before you can build the product variant components in lesson 4.

## Add enumerations

All enumerations follow the same process. In the Schema editor, click **+Add** next to **Enumerations** in the left sidebar. Fill in the display name and API ID, then add enumeration values one by one by entering the display name and clicking **+ Add**. Click **Add Enumeration** to save.

1. Go to **Schema**, and click **+Add** next to **Enumerations**.
2. Provide the following values for each enumeration, and click **Add Enumeration** to save.

    **Clothes size**

    |Field              |Input                                            |
    |-------------------|-------------------------------------------------|
    |Display name       |Clothes size                                     |
    |API ID             |ClothesSize                                      |
    |Enumeration values |One by one, add the following: XS, S, M, L, XL   |

    **Shoes size**

    | Field | Input |
    |---|---|
    | Display name | Shoes size |
    | API ID | ShoesSize |
    | Enumeration values | Size_35, Size_36, Size_37, Size_38, Size_39, Size_40, Size_41, Size_42, Size_43, Size_44 |

    **Wearable items color**

    | Field | Input |
    |---|---|
    | Display name | Wearable items color |
    | API ID | WearableItemsColor |
    | Enumeration values | Red, Green, Blue, Black, White |

    **Decor items color**

    | Field | Input |
    |---|---|
    | Display name | Decor items color |
    | API ID | DecorColor |
    | Enumeration values | Gold, Silver, Bronze, Cobalt |

After adding all enumerations, the left sidebar should look like this:

![Your enumerations listed in the schema](/images/docs/getting-started/enumerations-listed.png)

**Why separate enumerations for shoes and clothes sizes?** Shoes and clothing use different size scales. A single "size" enumeration would mix EU shoe sizes with clothing sizes, producing a dropdown that is inconvenient to use in the content editor. Separate enumerations keep each product type's fields meaningful and required.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-components-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 4.1 - Build components</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 2.1 - Configure reference fields

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-configure-reference-fields

In this lesson, you will add reference fields to the `Product` and `Landing page` models to connect them to other models in the schema. The reference type, direction, and cardinality configured here determine exactly what you will query later in the API Playground.

## Products and categories

Products need to be assignable to multiple categories, and categories need to display all their products. This requires a many-to-many, two-way reference. A two-way reference is required so you can query in both directions: from a product to its categories, and from a category to all its products.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9whb7jaef07w5i2wj3en0" caption="Adding a reference field" />

1. Open the **Product** model in the Schema editor and from the right sidebar, add a **Reference** field.
2. Configure the reference field with the following information:

    **Define relationship**

    | Field | Input |
    |---|---|
    | Reference type | Allow only one model to be referenced |
    | Model to reference | ProductCategory |
    | Reference directions | Two-way reference |
    | Allow multiple Products per ProductCategory | Select checkbox |
    | Allow multiple ProductCategories per Product | Select checkbox |
    | Relationship cardinality | The graphic displays that the relationship is of type many-to-many |

    **Configure reference**

    | Field | Input |
    |---|---|
    | Display name | Pre-configured. Leave as is. |
    | API ID | Pre-configured. Leave as is. |
    | Description | Select the categories that apply to your product |
    | Field visibility | Read / Write |

    **Configure reverse field**

    | Field | Input |
    |---|---|
    | Display name | Pre-configured. Leave as is. |
    | API ID | Pre-configured. Leave as is. |
    | Field visibility | Read / Write |

3. Click **Add** to save.

The reference field appears at the bottom of the model. Use the six-dot handle to drag it above the slug field.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/X7EG0VaxSjelihFLwc45" caption="Reorder reference field in schema" />
 
**What this enables:** In lesson 7, you will be able to query `productCategory(where: { slug: "sportswear" }) { products { productName } }`. The query returns all products within that category. This is possible because of the two-way direction configured here.

## Landing page references

The `Landing page` model needs to display featured blog posts, product categories, and seller information. Each of these is a one-way reference. The `Landing page` queries into those models, but those models do not need to query back into `Landing pages`.

1. Open the **Landing page** model in the Schema editor and from the right sidebar under **Relation**, select **Reference**.

2. Configure the reference field for the `Blog post` model with the following information:

    **Define relationship**

    | Field | Input |
    |---|---|
    | Reference type | Allow only one model to be referenced |
    | Model to reference | BlogPost |
    | Reference directions | One-way reference |
    | Allow multiple BlogPosts per LandingPage | Select checkbox |

    **Configure reference**

    | Field | Input |
    |---|---|
    | Display name | Pre-configured. Leave as is. |
    | API ID | Pre-configured. Leave as is. |
    | Description | Featured item |
    | Field visibility | Read / Write |

3. Click **Add** to save.

4. Add another **Reference** field from the right sidebar. Configure the reference field for the `Product category` model with the following information:

    **Define relationship**

    | Field | Input |
    |---|---|
    | Reference type | Allow only one model to be referenced |
    | Model to reference | ProductCategory |
    | Reference directions | One-way reference |
    | Allow multiple ProductCategories per LandingPage | Select checkbox |

    **Configure reference**

    | Field | Input |
    |---|---|
    | Display name | Pre-configured. Leave as is. |
    | API ID | Pre-configured. Leave as is. |
    | Description | Browse our categories |
    | Field visibility | Read / Write |

5. Click **Add** to save.

6. Add another **Reference** field from the right sidebar. Configure the reference field for the `Seller information` model with the following information:

    **Define relationship**

    | Field | Input |
    |---|---|
    | Reference type | Allow only one model to be referenced |
    | Model to reference | SellerInformation |
    | Reference directions | One-way reference |
    | Relation cardinality | To one |

    **Configure reference**

    | Field | Input |
    |---|---|
    | Display name | Pre-configured. Leave as is. |
    | API ID | Pre-configured. Leave as is. |
    | Description | Business information |
    | Field visibility | Read / Write |

7. Click **Add** to save.

Your Landing page model should now look like this:

![Your Landing page model so far](/images/docs/getting-started/landing-page-model-with-references.png)

**Why one-way for Landing page references, but two-way for Products and categories?**
A Blog post, Product category, or Seller information entry has no use case for querying which landing pages reference it. The two-way reference on Products and categories exists because the project needs to navigate from both sides. Where that bidirectional query isn't needed, a one-way reference keeps the schema clean.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-enumerations-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 3 - Enumerations</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 9.1 - Configure webhooks

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-configure-webhooks

In this lesson, you will configure a webhook that triggers a new deployment whenever a product entry is published in Hygraph. Without this, publishing content in Hygraph does not update the live storefront and the deployed site continues to show the version built at the last deployment.

## Generate a build hook

Before configuring the webhook in Hygraph, generate a build hook URL on your deployment platform. Hygraph will send a POST request to this URL whenever the webhook fires.

### Netlify

1. Go to your site in Netlify and navigate to **Project configuration > Build & deploy > Continuous deployment > Build hooks**.
2. In the **Build hook name** field, enter `Deploy from Hygraph`.
3. In the **Branch to build** dropdown, select `main`.
4. Click **Save**.
5. Copy the generated URL.

### Vercel

1. Go to your project in Vercel and navigate to **Settings > Git > Deploy Hooks**.
2. In the hook name field, enter `Deploy from Hygraph`.
3. In the branch field, enter `main`.
4. Click **Create Hook**.
5. Copy the generated URL.

## Configure the webhook in Hygraph

1. Navigate to **Project Settings > Automation > Webhooks** in your Hygraph project.
2. Click **Add webhook**.
3. Fill in the following information:

    | Field | Input |
    |---|---|
    | Name | Deploy to Storefront |
    | Description | Trigger published |
    | Include payload | Enable to send data via the webhook |
    | Method | POST |
    | URL | Paste the build hook URL copied from Netlify or Vercel |
    | Secret key | Generate a strong random string and enter it here. See the note below. |
    | Headers | Leave blank |

    **The secret key** is how the receiving endpoint verifies the request came from Hygraph. Without it, any POST request to the build hook URL triggers a deployment. Add a strong secret and store it securely.

4. Under **Triggers**, configure the following:

    | Field | Input |
    |---|---|
    | Content model | Product |
    | Stage | PUBLISHED |
    | Actions | Leave empty |
    | Sources | Leave empty |

    You need to select the `Product` model because product content is what the storefront displays. Selecting `PUBLISHED` means the webhook only fires when content is published, and saving a content entry does not trigger a deployment. Leaving `Actions` and `Sources` empty acts as a wildcard: all publish actions from all sources trigger the webhook.

5. Click **Add webhook** to save.

Publishing any `Product` entry in Hygraph automatically triggers a new storefront deployment.

## Verify the webhook

To verify the webhook is working, publish a content entry and confirm a new build starts on your deployment platform.

1. Navigate to **Content** and open any `Product` entry.
2. Modify the product entry, for example, edit the product description.
3. Click **Save & Publish**.
4. Check your deployment platform for a new build.
    - **Netlify**: Navigate to **Deploys** in your Netlify site and check if a new build appears at the top of the list, triggered by the webhook.
    - **Vercel**: Navigate to **Deployments** in your Vercel project and check if a new deployment appears, triggered by the webhook.

If no build starts, check the following:
- The webhook URL matches the build hook URL exactly. There should be no trailing spaces or missing characters.
- The content entry you published belongs to the **Product** model. The trigger is scoped to Product only.
- The entry moved to the `PUBLISHED` stage. Saving an entry does not trigger the webhook.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-wrap-up"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Go to the wrap-up</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 8.2 - Connect the storefront

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-connect-storefront

In this lesson, you will configure Content API access in Hygraph and add two environment variables to the starter. By the end, the storefront is running locally and displaying published content.

## Two access modes

Before configuring anything, it helps to understand why there are two separate configurations.

Hygraph exposes a single Content API endpoint. The starter uses two different ways to access content through that endpoint:

- **The Content API** serves the storefront for public visitors. It only returns content in the `PUBLISHED` stage. No authentication is required.
- **A Permanent Auth Token (PAT)** grants the frontend access to `DRAFT` content. It is used only for the preview URL configured in lesson 8.3. 

## Configure Content API permissions

The Public Content API needs read permissions initialized before unauthenticated requests can return content.

1. Navigate to **Project settings > Access > Content API**.
2. In the **Content Permissions** box, click **Initialize defaults**.

    The content permissions box now looks like this:

    ![Content permissions initialized](/images/docs/getting-started/public-content-api-permissions.png)

3. Navigate to **Project settings > Access > Endpoints**. Copy the **High Performance Content API** endpoint URL from this screen. You will need it while [adding environment variables](#add-environment-variables).

<Alert theme="info" title="Content API permissions">
For a full reference on public API permissions, see [Public API permissions](/docs/api-reference/basics/authorization#public-api-permissions).
</Alert>

## Create a PAT for draft content

1. Navigate to **Project settings > Access > Permanent Auth Tokens**.
2. Click **+ Add token**.
3. Enter a name and optional description, select **DRAFT** as the default stage for content delivery, and click **Add & configure permissions**.
4. On the token details screen, copy the token value. You will need it while [adding environment variables](#add-environment-variables).

<Alert theme="info" title="PAT documentation">
For a full reference on Permanent Auth Tokens, see [Authorization](/docs/api-reference/basics/authorization).
</Alert>

## Add environment variables

Copy the `.env.sample` file and rename it to `.env.local`:

```bash
cp .env.sample .env.local
```

Open `.env.local` and add the two values collected above:

```bash
HYGRAPH_ENDPOINT=YOUR_CONTENT_API_ENDPOINT_HERE
HYGRAPH_DEV_AUTH_TOKEN=YOUR_DRAFT_TOKEN_HERE
HYGRAPH_PREVIEW_SECRET=
```

Leave `HYGRAPH_PREVIEW_SECRET` empty for now. You will configure it in the next lesson.

## Run the storefront

Start the local development server:

```bash
npm run dev
```

Open `http://localhost:3000` in your browser. The storefront should display your published content.

![Starter homepage](/images/docs/getting-started/starter-homepage.png)

![Product page](/images/docs/getting-started/product-page.png)

<Alert theme="warning" title="Storefront appears blank?">
The Content API only returns content in the `PUBLISHED` stage. If the storefront is blank, open the content editor and verify that all content entries created in lesson 6.1 are published.
</Alert>

<Alert theme="info" title="About the starter">
The storefront renders your landing pages, product pages, navigation, and review data using the same GraphQL queries practiced in lesson 7.1. The `utils/` directory in the starter contains the query functions. Spend some time exploring the code in your editor to understand how the Hygraph content maps to the frontend components.
</Alert>

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-preview-url"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 8.3 - Configure a preview URL</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 1 - Content models

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-content-models-overview

This section covers planning the content structure of the e-commerce project and building it in the Hygraph schema editor.

The field names, model relationships, and component structures defined here are what the API exposes and the frontend consumes. Everything configured in later lessons, such as queries, mutations, frontend connection, and webhooks, depends on the schema built here.

By the end of lesson 1.2, the project contains the following models with their initial fields:

- Product
- Product category
- Blog post
- Seller information
- Landing page
- Navigation

These models are intentionally incomplete at this stage. References are added in lesson 2, components in lesson 4, and remote fields in lesson 5. The schema is built in layers, not all at once.

## Key terms

Before building, the following terms appear in the schema editor:

![Project models](/images/docs/getting-started/hygraph-project-models.png)

**Schema:** The complete content structure of your project. It contains your models, components, enumerations, and remote sources.

**Models:** Containers that define the shape of a content type. A `Product` model defines what a product entry looks like. When an editor creates a product, they fill in the fields that model defines.

**Fields:** The individual data points stored on a model. A `Product` model might contain a `name` field (Single line text), a `price` field (Float), and an `image` field (Asset picker). Fields have types, and those types determine what data can be stored and how it can be queried.

<Alert theme="info" title="Scalars">
In GraphQL, field types are called scalars. Hygraph provides scalar types for strings, integers, floats, booleans, dates, colors, geo-coordinates, and more. These appear in the schema editor's right sidebar when adding a field.
</Alert>

## Lessons in this section

The following lessons apply content modeling concepts directly to this project. For a deeper understanding of those concepts, read [Content modeling in Hygraph](/docs/core-concepts/content-modeling/content-modeling-in-hygraph).

| Lesson | What you will do |
|---|---|
| [1.1 Design your content models](/docs/getting-started/tutorial/tutorial-design-content-models) | Map the models, components, enumerations, and remote data the project needs before touching the schema editor |
| [1.2 Build your content models](/docs/getting-started/tutorial/tutorial-build-content-models) | Create the base models and add their initial fields in the Hygraph schema editor |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-design-content-models"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 1.1 - Design your content models</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Content

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-content-overview

This section covers creating all the content the e-commerce project needs and understanding how the content editor reflects the schema built in earlier lessons.

Every field, dropdown, reference, and component you see here was configured in lessons 1 through 5. If a product variant presents only size and color fields for the selected product type, that is the modular component from lesson 4.1 working as intended. If a category reference allows selecting multiple categories per product, that is the many-to-many configuration from lesson 2.1. The content editor is where schema decisions become testable.

By the end of lesson 6.3, the project contains:

- Published product categories
- Core product entries with related products, images, and variants
- Seller information entry
- Landing pages with `Stripes` components
- Navigation entry with links
- Localized Spanish content for the Summer Campaign and products
- Published content ready to query in the API Playground

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [6.1 Create content](/docs/getting-started/tutorial/tutorial-create-content) | Create product categories, seller information, products, landing pages, and navigation entries |
| [6.2 Localize content](/docs/getting-started/tutorial/tutorial-localize-content) | Add a Spanish locale and write localized content for the Summer Campaign and products |
| [6.3 Understand content stages](/docs/getting-started/tutorial/tutorial-content-stages) | Learn how DRAFT and PUBLISHED stages affect what the Content API returns and what the frontend displays |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-create-content"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 6.1 - Create content</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# 6.3 Understand content stages

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-content-stages

Content stages in Hygraph are not just an editorial workflow feature. They determine what the Content API returns and what your frontend displays. Understanding this now prevents the most common source of confusion when connecting the frontend in lesson 8.

## DRAFT and PUBLISHED

Hygraph provides two system content stages: `DRAFT` and `PUBLISHED`.

Every content entry starts in `DRAFT`. When you click **Save & Publish**, the entry is promoted to `PUBLISHED`. At that point, the entry exists in both stages simultaneously. `DRAFT` always reflects the current state of the entry, and `PUBLISHED` reflects the last published version.

When you edit a published entry and click **Save** without publishing, the entry becomes **outdated**. The `DRAFT` stage contains changes that have not yet been promoted to `PUBLISHED`. The published version on the frontend remains unchanged until you publish again.

![Table showing content in stages DRAFT, PUBLISHED, and outdated](/images/docs/getting-started/content-stages-comparison.png)

**The API consequence:** Hygraph uses a single Content API endpoint. Which stage you read depends on how access is configured via public permissions, a Permanent Auth Token (PAT), or stage headers and query parameters. Unauthenticated public access with default permissions only returns entries that have been published. If an entry has never been published, those requests return no data for that entry.

In lesson 8.2, you will configure a Permanent Auth Token (PAT) that grants the frontend access to draft content for preview purposes. The public storefront uses unauthenticated access configured for the `PUBLISHED` stage. Understanding the distinction now means that when you see different results in the API Playground versus the frontend, you will know why.

<Alert theme="info" title="Custom content stages">
Hygraph also supports custom content stages. For example, a Review stage between DRAFT and PUBLISHED for editorial workflows that require approval before publishing. See [Content stages](/docs/developer-guides/content/content-stages) for details.
</Alert>

## Save vs Save & Publish

Every time you create or edit a content entry, you choose between two actions:

- **Save** stores the changes in the `DRAFT` stage only. The published version is not updated. Use this when content needs review before going live.
- **Save & Publish** stores the changes in `DRAFT` and promotes them to `PUBLISHED` simultaneously. Use this when content is ready to be consumed by the frontend.

![Save and Save & publish buttons](/images/docs/getting-started/save-publish-options.png)

All entries created in lesson 6.1 used **Save & Publish**, which means they exist in both `DRAFT` and `PUBLISHED`. If you used **Save** only at any point, those entries will not appear in responses configured for the `PUBLISHED` stage, including in the connected storefront.

<Alert theme="warning">
If your frontend appears to be missing content after connecting it in lesson 8, check whether the relevant entries have been published. An entry that exists in `DRAFT` only is not visible when querying for the `PUBLISHED` stage.
</Alert>

## Content duplication

Hygraph lets you duplicate content entries to save time when creating similar entries.

To duplicate an entry, open it in the edit view and click the duplication icon at the top of the screen. The duplicate loads with the same field values as the original, with `(copy)` appended to the title field.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9whjchtq207vx0vn0qwx1" caption="Content duplication" />

<Alert theme="warning">
If a duplicated entry contains reference fields, some relations are duplicated and others are not. The system notifies you when this is the case. See [Duplicating content](/docs/developer-guides/content/duplicating-content) for details on which relations are preserved.
</Alert>

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-queries-mutations-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 7 - Queries and mutations</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# 6.1 Create content

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-create-content

In this lesson, you will populate the e-commerce project with content. The fields, dropdowns, references, and components in the content editor are a direct result of the schema built in lessons 1 through 5. If anything looks unexpected, it is worth returning to the relevant schema lesson to verify the configuration.

The lesson is structured in stages because some content depends on other content existing first. Products cannot have related products until other products exist. Landing pages cannot reference blog posts or categories until those entries are published. Follow the sections in order.

## Assets

The cloned project already contains product images. You need to add alt text and a caption to the headband image to get started.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/9E8rOBuAQFujFeJbLMx3" caption="Add alt text and caption to assets" />

1. In your Hygraph project, click **Assets**. 
2. Type `headband` in the search filter.
3. Open the first result to edit the asset.
4. Fill in the following fields and click **Save & Publish**:

    | Field | Input |
    |---|---|
    | Alt text | Cotton headband |
    | Caption | A soft white cotton headband |

5. Click the back arrow next to **Edit Asset** at the top left to return to the assets table.
6. Click the **X** next to the search filter to reset it.

<Alert theme="info" title="Additional practice">
For alt text and caption data for all remaining assets, see [Create content — additional practice](/docs/getting-started/tutorial/tutorial-create-content-additional-practice#assets). Adding this data is optional and does not affect the frontend connection.
</Alert>

## Product categories

The `Product category` model was created in lesson 1.2 and connected to the `Product` model through a many-to-many reference in lesson 2.1. Each category entry created here can later be assigned to multiple products, and each product can belong to multiple categories.

No product entries exist yet, so you will create the categories first and add product assignments later.

1. Go to **Content**, and under **Default Views**, click **Product category**.
2. Click **+ Add entry**.
3. Create the following entry and click **Save & Publish**:

    | Field | Input |
    |---|---|
    | Category name | Clothes |
    | Slug | clothes |
    | Description | You will find clothes here |

Repeat the process for each of the following categories:

| Category name | Slug | Description |
|---|---|---|
| Shoes | shoes | You will find shoes here |
| Sportswear | sportswear | You will find sportswear here |
| Urban | urban | You will find urban-style items here |
| New arrival | new-arrival | You will find our latest arrivals here |
| Decor | decor | You will find decor items here |
| Accessories | accessories | You will find accessories here |

Some categories overlap by design. Because the reference between products and categories is many-to-many, one product can belong to both New arrival and Sportswear at the same time.

Your Product categories view should now look like this:

![Product categories in the content editor with entries](/images/docs/getting-started/product-category-table-full.png)

## Seller information

The Seller information model holds business details that the landing page references. Create a single entry.

1. Go to **Content**, and under **Default Views**, click **Seller information**.
2. Click **+ Add entry**.
3. Fill in the following fields and click **Save & Publish**:

    | Field | Input |
    |---|---|
    | Business name | My business |
    | Slug | my-business |
    | Business logo | Click **Add business logo**, select the Hygraph logo from your assets, and click the relation icon in the first column to add it |
    | Business description | This is a description of my business |

Your Seller information view should look like this:

![Seller information content editor view with entry](/images/docs/getting-started/seller-information-table.png)

## Products

Product entries are created in two steps. In this step, you will create the basic product listing. Related products are added in the next step, once all product entries exist.

1. Go to **Content**, and under **Default Views**, click **Product**.
2. Click **+ Add entry**.

        ![Add product content entry](/images/docs/getting-started/add-product-content-entry.png)

3. Create the first entry using the following information:

    | Field | Input |
    |---|---|
    | Product name | Black leather shoes |
    | Product slug | black-leather-shoes |
    | Product category | Click **Add existing Product categories** and select **Shoes** and **New arrival** |
    | Product image | Click **Add Product images**, type `black leather shoes` in the search filter, and click **Add selected images** |
    | Product description | These black leather shoes seamlessly blend sophistication with durability, making them a versatile choice for both formal occasions and everyday wear. The sleek design and high-quality leather ensure a timeless appeal that complements any outfit. |
    | Product variant | Click **Add component**, select **Shoes**, then set Size to `Size_40` and Color to `Black` |
    | Product price | 170 |

    `Product variant` is the modular component field built in lesson 4.1. Clicking **Add component** presents the four product type options — `Clothing`, `Shoes`, `Accessories`, `Decor`. Selecting `Shoes` reveals only the shoe size and color fields, not the clothing size fields. This is the modular component working as configured.

4. Click **Save & Publish**.

![Product content entry](/images/docs/getting-started/product-content-entry.png)

Now create the remaining product entries using the following information:

**Blue running shoes**

| Field | Input |
|---|---|
| Product name | Blue running shoes |
| Product slug | blue-running-shoes |
| Product category | Select **Sportswear** and **Shoes** |
| Product image | Select images with file name **blue running shoes** |
| Product description | These blue running shoes offer both form and function, providing exceptional support and style for your active pursuits. The breathable material and cushioned sole ensure a comfortable experience mile after mile. |
| Product variant | Select **Shoes**, then Size `Size_42` and Color `Blue` |
| Product price | 130 |

**Plaid shirt**

| Field | Input |
|---|---|
| Product name | Plaid shirt |
| Product slug | plaid-shirt |
| Product category | Select **New arrival**, **Urban**, and **Clothes** |
| Product image | Select images with file name **blue plaid shirt** |
| Product description | This plaid shirt exudes a timeless charm, perfect for a casual day out or a relaxed evening gathering. The classic checkered pattern and comfortable fit make it a wardrobe staple for effortless style. |
| Product variant | Select **Clothing**, then Size `XL` and Color `Blue` |
| Product price | 60 |

**Necklace**

| Field | Input |
|---|---|
| Product name | Necklace |
| Product slug | necklace |
| Product category | Select **Accessories** |
| Product image | Select images with file name **necklace** |
| Product description | This white necklace is crafted from parts of seashells, evoking a relaxed, beachy vibe. Perfect for those looking to add a touch of the sea to their daily style. |
| Product variant | Select **Accessories**, then Color `White` |
| Product price | 12 |

**Headband**

| Field | Input |
|---|---|
| Product name | Headband |
| Product slug | headband |
| Product category | Select **Accessories** |
| Product image | Select images with file name **headband** |
| Product description | This white cotton headband provides an elegant and sophisticated touch to your hairstyle. Perfect for completing your look with a blend of fashion and comfort. |
| Product variant | Select **Accessories**, then Color `White` |
| Product price | 9 |

<Alert theme="info" title="Additional practice">
For adding more product entries, see [Create content — additional practice](/docs/getting-started/tutorial/tutorial-create-content-additional-practice#products). Adding these is optional but some API Playground query exercises in lesson 7.1 reference them.
</Alert>

## Related products

Now that you've created all product entries, you can add related products to each one.

1. Open the **Headband** entry to edit it.
2. Scroll to the **Related Products** component and click **+ Add Related Products**.

    The **Title** field is read-only and displays `Related Products`. This is because you set the field to read-only with an initial value when building the component in lesson 4.1. So, every instance of this component shows the same heading.

3. Click **Add existing products** and select: black leather shoes, necklace, blue running shoes, and plaid shirt.
4. Click **Add selected products**, then click **Save & Publish**.

![Component with related products](/images/docs/getting-started/related-products-component.png)

Repeat for the remaining product entries:

| Product entry | Related products |
|---|---|
| Blue running shoes | black leather shoes, necklace, headband, plaid shirt |
| Black leather shoes | blue running shoes, necklace, headband, plaid shirt |
| Necklace | black leather shoes, blue running shoes, headband, plaid shirt |
| Plaid shirt | black leather shoes, necklace, headband, blue running shoes |

<Alert theme="info" title="Additional practice">
For related product assignments for the additional practice entries, see [Create content — additional practice](/docs/getting-started/tutorial/tutorial-create-content-additional-practice#related-products).
</Alert>

## Blog post

Create a blog post entry to use on the landing page.

1. Go to **Content**, and under **Default Views**, click **Blog post**.
2. Click **+ Add entry** and fill in the following:

    | Field | Input |
    |---|---|
    | Title | Our new leather shoes |
    | Slug | Auto-completes from the title. Leave as is. |
    | Body | Type `Take a look at this awesome new arrival`. Then click **Embed**, select **Block**, choose the **Product** model from the dropdown, click **Select model**, and select the **Black leather shoes** entry. |

3. Click **Save & Publish**.

Your blog post entry should look like this:

![Blog post complete entry](/images/docs/getting-started/blog-post-entry.png)

## Landing pages

You will create two landing pages: a homepage and a Summer Campaign page. The homepage could not have been created earlier because it references seller information, blog posts, and products that needed to exist first.

### Homepage

1. Go to **Content**, and under **Default Views**, click **Landing page**.
2. Click **+ Add entry** and fill in the following:

    | Field | Input |
    |---|---|
    | Landing page title | Home |
    | Link | `/` |
    | Blog posts | Leave empty for now |
    | Product categories | Leave empty for now |
    | Seller information | Add the seller information entry created earlier |
    | Stripes | Click **+ Add component** and add a `Call to Action` and a `Product Grid` using the information below |

    **Call to Action:**

    | Field | Input |
    |---|---|
    | Heading | Main Headline for the page |
    | Body | We provide amazing products from outerwear, shoes, home goods, and more! Be sure to check out all the amazing products. |
    | Image | Add the Hygraph Logo asset |
    | Button | Click **+ Add Button**, enter `Shop Now` in the Text field and `https://google.com` in the URL field |

    **Product Grid:**

    | Field | Input |
    |---|---|
    | Headline | Picks of the month |
    | Products | Add relations to: blue running shoes, black leather shoes, necklace, headband, plaid shirt |

3. Click **Save & Publish**.

Your homepage entry should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9whlfhtqa07vx00gskfs7" caption="Homepage complete entry" />

### Summer Campaign

1. Go to **Content**, and under **Default Views**, click **Landing page**.
2. Click **+ Add entry** and fill in the following:

    | Field | Input |
    |---|---|
    | Landing page title | Summer Campaign |
    | Link | summer-campaign |
    | Blog posts | Leave empty for now |
    | Product categories | Leave empty for now |
    | Seller information | Add the seller information entry created earlier |
    | Stripes | Click **+ Add component** and add a `Call to Action` and a `Product Grid` using the information below |

    **Call to Action:**

    | Field | Input |
    |---|---|
    | Heading | Get ready for summer with these amazing deals |
    | Body | The Summer Sale is in full swing! See the amazing summer deals we have listed below! |
    | Image | Leave empty |
    | Button | Leave empty |

    **Product Grid:**

    | Field | Input |
    |---|---|
    | Headline | Summer wear |
    | Products | Add relations to: blue running shoes, black leather shoes, necklace, headband, plaid shirt |

3. Click **Save & Publish**.

## Navigation

The `Navigation` model uses the `Link` component built in lesson 4.1. Each `Nav Link` entry in the navigation maps to one link in the frontend navigation bar.

1. Go to **Content**, and under **Default Views**, click **Navigation**.
2. Click **+ Add entry** and fill in the following:

    | Field | Input |
    |---|---|
    | Nav ID | main |

3. Click **+ Add Link** to add the first Nav Link component and fill in:

    | Field | Input |
    |---|---|
    | Display Text | Clothes |
    | Page | Leave empty |
    | External URL | `/category/clothes` |

4. Click **+ Add another Link** and repeat for each of the following:

    **Shoes**

    | Field | Input |
    |---|---|
    | Display Text | Shoes |
    | Page | Leave empty |
    | External URL | `/category/shoes` |

    **Accessories**

    | Field | Input |
    |---|---|
    | Display Text | Accessories |
    | Page | Leave empty |
    | External URL | `/category/accessories` |

    **Decor**

    | Field | Input |
    |---|---|
    | Display Text | Decor |
    | Page | Leave empty |
    | External URL | `/category/decor` |

    **Summer Campaign**

    | Field | Input |
    |---|---|
    | Display Text | Summer Campaign |
    | Page | Click **Add existing document** and select the Summer Campaign landing page |
    | External URL | Leave empty |

5. Click **Save & Publish**.

The navigation entry now contains all the links the frontend needs. These will be visible when the storefront is connected in lesson 8.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-localize-content"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 6.2 - Localize content</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Content creation — additional practice

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-create-content-additional-practice

This page contains optional additional content for lesson 6.1. None of this is required for the frontend to connect and function. Some of the additional product entries are referenced in more advanced API Playground exercises in lesson 7.1.

Content on this page depends on other content existing first. You cannot localize an alt text field that was never filled in. You cannot add related products that were never created.

## Assets

Add alt text and captions to the following assets using the same process as in lesson 6.1:

| Asset | Alt text | Caption |
|---|---|---|
| Green hoodie | Green hoodie | A comfortable green hoodie, 100% cotton |
| Blue running shoes | Blue running shoes | A pair of lightweight blue running shoes |
| Red urban shoes | Red urban shoes | A pair of stylish and modern red urban shoes |
| Blue plaid shirt | Blue plaid shirt | A classic and warm blue plaid shirt |
| Black leather shoes | Black leather shoes | A pair of elegant black leather shoes |
| Coffee table | Coffee table | Coffee table with glass top and metal legs |
| Coffee tray | Coffee tray | Metal coffee tray for two cups |
| Floor lamp | Floor lamp | Floor lamp with paper top and bronze details |
| Vase | Vase | Small metal vase |
| Desk lamp | Desk lamp | An elegant silver lamp |
| Bag | Green bag | A modern green leather bag |
| Necklace | White necklace | A lovely white necklace with summer vibes |
| Wallet | Black leather wallet | A black leather wallet with space for all your cards |
| Fanny pack | Red fanny pack | A modern red fanny pack to carry your essentials |
| Headband | Cotton headband | A soft white cotton headband |

[Return to lesson 6.1 — Create content](/docs/getting-started/tutorial/tutorial-create-content#assets)

## Products

Create the following additional product entries using the same process as in lesson 6.1.

**Green Hoodie**

| Field | Input |
|---|---|
| Product name | Green Hoodie |
| Product slug | green-hoodie |
| Product category | Select **Clothes**, **Sportswear**, and **New arrival** |
| Product image | Select images with file name **green hoodie** |
| Product description | This green hoodie combines comfort and style seamlessly, making it your go-to choice for a casual yet trendy look. Its soft fabric and versatile shade of green make it a wardrobe essential for all seasons. |
| Product variant | Select **Clothing**, then Size `L` and Color `Green` |
| Product price | 45 |

**Desk lamp**

| Field | Input |
|---|---|
| Product name | Desk lamp |
| Product slug | desk-lamp |
| Product category | Select **Decor** |
| Product image | Select images with file name **desk lamp** |
| Product description | This silver desk lamp illuminates your workspace with elegance and style. Its modern design and sleek silver finish make it a standout piece for your desk. |
| Product variant | Select **Decor**, then Color `Silver` |
| Product price | 35 |

**Wallet**

| Field | Input |
|---|---|
| Product name | Wallet |
| Product slug | wallet |
| Product category | Select **Accessories** |
| Product image | Select images with file name **wallet** |
| Product description | This black leather wallet combines functionality and style in a modern, compact design. With ample space for your cards and cash, it's the perfect accessory for carrying your essentials with elegance. |
| Product variant | Select **Accessories**, then Color `Black` |
| Product price | 39 |

**Urban shoes**

| Field | Input |
|---|---|
| Product name | Urban shoes |
| Product slug | urban-shoes |
| Product category | Select **Shoes** and **Urban** |
| Product image | Select images with file name **red urban shoes** |
| Product description | These red urban shoes effortlessly blend fashion with comfort, making a bold statement in any cityscape. The sleek design and cushioned insole ensure both style and ease for your urban adventures. |
| Product variant | Select **Shoes**, then Size `Size_38` and Color `Red` |
| Product price | 130 |

**Colorful socks**

| Field | Input |
|---|---|
| Product name | Colorful socks |
| Product slug | colorful-socks |
| Product category | Select **Clothes**, **Urban**, **Accessories**, and **New arrival** |
| Product image | Select images with file name **colorful socks** |
| Product description | These vibrant socks are designed to add a touch of joy to your everyday style. With eye-catching colors and a comfortable fit, they're the perfect choice to express your personality with every step. |
| Product variant | Select **Accessories**, then Color `Red` |
| Product price | 12 |

**Floor lamp**

| Field | Input |
|---|---|
| Product name | Floor lamp |
| Product slug | floor-lamp |
| Product category | Select **Decor** |
| Product image | Select images with file name **floor lamp** |
| Product description | This floor lamp seamlessly blends the warmth of paper with metal and wooden details, adding a modern and elegant touch to your space. Its unique design softly and harmoniously lights up your surroundings. |
| Product variant | Select **Decor**, then Color `Bronze` |
| Product price | 240 |

**Coffee table**

| Field | Input |
|---|---|
| Product name | Coffee table |
| Product slug | coffee-table |
| Product category | Select **Decor** |
| Product image | Select images with file name **coffee table** |
| Product description | This coffee table blends elegance and modernity with its glass surface and metal legs. Perfect to add a contemporary touch to your living space. |
| Product variant | Select **Decor**, then Color `Silver` |
| Product price | 199 |

**Coffee tray**

| Field | Input |
|---|---|
| Product name | Coffee tray |
| Product slug | coffee-tray |
| Product category | Select **Decor** |
| Product image | Select images with file name **coffee tray** |
| Product description | This metal coffee tray is crafted for two cups, adding a touch of industrial style to your coffee experience. Its sleek and durable design makes it a perfect addition to your morning routine. |
| Product variant | Select **Decor**, then Color `Silver` |
| Product price | 19 |

**Vase**

| Field | Input |
|---|---|
| Product name | Vase |
| Product slug | vase |
| Product category | Select **Decor** |
| Product image | Select images with file name **vase** |
| Product description | This small metal vase is versatile and stylish, perfect for displaying fresh flowers or storing bathroom items like makeup brushes. Its modern design easily complements any space. |
| Product variant | Select **Decor**, then Color `Silver` |
| Product price | 15 |

**Bag**

| Field | Input |
|---|---|
| Product name | Bag |
| Product slug | bag |
| Product category | Select **Accessories** |
| Product image | Select images with file name **bag** |
| Product description | This green leather bag is the perfect accessory to carry your belongings with style and elegance. Crafted from high-quality leather, its spacious and modern design is perfect for any occasion. |
| Product variant | Select **Accessories**, then Color `Green` |
| Product price | 52 |

**Fanny pack**

| Field | Input |
|---|---|
| Product name | Fanny pack |
| Product slug | fanny-pack |
| Product category | Select **Accessories** |
| Product image | Select images with file name **fanny pack** |
| Product description | This red fanny pack is the perfect accessory to carry your essentials comfortably and in style. Its vibrant color and modern design make it the ideal choice for your daily adventures. |
| Product variant | Select **Accessories**, then Color `Red` |
| Product price | 14 |

[Return to lesson 6.1 — Create content](/docs/getting-started/tutorial/tutorial-create-content#products)

## Related products

Add related product assignments to the following additional entries:

| Product entry | Related products |
|---|---|
| Green Hoodie | colorful socks, blue running shoes, urban shoes, plaid shirt |
| Desk lamp | floor lamp, coffee table, coffee tray, vase |
| Wallet | bag, necklace, headband, fanny pack |
| Urban shoes | colorful socks, blue running shoes, plaid shirt, black leather shoes |
| Floor lamp | coffee table, coffee tray, vase, desk lamp |
| Coffee table | floor lamp, coffee tray, vase, desk lamp |
| Coffee tray | floor lamp, coffee table, vase, desk lamp |
| Vase | floor lamp, coffee table, coffee tray, desk lamp |
| Bag | wallet, necklace, headband, fanny pack |
| Fanny pack | wallet, bag, necklace, headband |

[Return to lesson 6.1 — Create content](/docs/getting-started/tutorial/tutorial-create-content#related-products)


---
# 1.1 Design your content models

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-design-content-models

In this lesson, you will map the content structure the project requires before building anything in the schema editor. This lesson has no steps to complete in Hygraph. The decisions made here determine every field, reference, and component configured in the lessons that follow.

<Alert theme="info" title="New to content modeling?">
Read [Content modeling in Hygraph](/docs/core-concepts/content-modeling/content-modeling-in-hygraph) to understand the underlying concepts first.
</Alert>

## The project

The e-commerce project sells wearables and home goods. Before opening the schema editor, you need to map the content structure against what the store must do.

![Content modeling](/images/docs/getting-started/content-modeling-matters.png)

The store has four goals:

- **Display product listings with enough detail for a buyer to make a decision**: image, size, color, price, description, and reviews.
- **Organize products into categories**, where one product can belong to multiple categories and one category can contain multiple products.
- **Display related products on each product page** to encourage further exploration.
- **Support a landing page, a blog, seller information, and a navigation structure**.

Reviews come from an external source. You will not store them in Hygraph. Instead, you will fetch them from a remote API using Content Federation.

## Proposed content flow

Based on those goals, here is what the schema will contain.

![Project structure](/images/docs/getting-started/hygraph-project-structure.png)

**Models**

| Model | Purpose |
|---|---|
| `Product` | Product listings with name, slug, images, description, price, and variant |
| `Product category` | Categories that products can be assigned to |
| `Blog post` | Articles promoting products |
| `Seller information` | Business details referenced from the landing page |
| `Landing page` | Flexible pages built from component sections |
| `Navigation` | Site navigation built from Link components |

**Components**

| Component | Purpose |
|---|---|
| Product Variant | Modular component for product type selection (Clothing, Shoes, Accessories, or Decor) |
| Clothing | Size and color fields for clothing items |
| Shoes | Size and color fields for footwear |
| Accessories | Color field for accessories |
| Decor | Color field for decor items |
| Related products | A set of product references for related product sections |
| Call to Action | Heading, body, image, and button for CTA sections |
| Button | Text and URL for use inside CTA components |
| Product Grid | Headline, description, and product references for grid sections |
| Link | Display text, URL, and page reference for navigation links |

**Product Variant as a modular component, not separate models.**
The store sells clothing, shoes, accessories, and decor. Each product type requires different fields. Shoes need a shoe size, clothing needs a clothing size, accessories need neither. Rather than creating four separate product models, the schema uses a single Product model with a modular component field. The component presents only the relevant fields based on the product type selected in the content editor. 

**Enumerations**

| Enumeration | Values |
|---|---|
| Clothes size | XS, S, M, L, XL |
| Shoes size | Size_35 through Size_44 |
| Wearable items color | Red, Green, Blue, Black, White |
| Decor items color | Gold, Silver, Bronze, Cobalt |

**Remote source**

| Source | Purpose |
|---|---|
| HyDemoAPI | Fetches product reviews from an external REST API. Configured as a Remote Field on the Product model and a Top-level Remote Field on the Query model. |

**Reviews as a remote field, not a model.**
Reviews exist in a third-party system. Migrating them into Hygraph would duplicate data and create a synchronization problem. A remote source connects to the origin directly. Review data appears in the API response alongside Hygraph content, with no migration required.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-build-content-models"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 1.2 - Build your content models</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 3 - Enumerations

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-enumerations-overview

This section covers creating the enumerations the product variant components depend on.

An enumeration defines a fixed set of allowed values at the schema level. The enumerations configured here, `Clothes size`, `Shoes size`, `Wearable items color`, and `Decor items color`, power the size and color dropdowns in the content editor in later lessons. They need to exist in the schema before the components that use them can be built.

## How enumerations work

An enumeration defines a fixed set of allowed values for a field. When a field is typed to an enumeration, the API enforces the allowed values at the schema level. A product entry cannot be published with a color value of "navy" if the enumeration only contains Red, Green, Blue, Black, and White.

This is different from a free-text field, where any value is accepted, and different from a reference, where values are editor-managed content entries. Use an enumeration when the set of valid values is fixed, controlled by the schema owner, and unlikely to be extended by editors. [Learn more about enumerations](/docs/developer-guides/schema/using-enumerations).

<Alert theme="info" title="Enumerations vs references vs taxonomies">
Use a reference when the list of values needs to be managed as content entries by editors. Use a taxonomy when the values are hierarchical. Enumerations are for flat, schema-controlled value sets that change infrequently.
</Alert>

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [3.1 Configure enumerations](/docs/getting-started/tutorial/tutorial-configure-enumerations) | Create enumerations for product size and color values that the product variant components will use |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-configure-enumerations"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 3.1 - Configure enumerations</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.



---
# Lesson 8 - Frontend connection

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-frontend-overview

This section covers setting up the Next.js e-commerce starter, connecting it to your Hygraph project, and configuring a preview URL for draft content.

The work in this section is configuration only. The starter handles all the frontend code for routing, components, queries, and styling. You need to provide the environment variables that tell the starter where to find your Hygraph project and how to authenticate.

The starter uses two different ways to access your Hygraph content:
- **The Content API** serves public visitors. It only returns content that has been explicitly published. 
- **A Permanent Auth Token (PAT)** grants the frontend access to draft content for preview purposes. 

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [8.1 Set up the frontend starter](/docs/getting-started/tutorial/tutorial-frontend-setup) | Clone the Next.js e-commerce starter, install dependencies, and orient yourself to the repo structure |
| [8.2 Connect your storefront](/docs/getting-started/tutorial/tutorial-connect-storefront) | Configure Content API permissions, create a PAT, and add the environment variables that connect the starter to your Hygraph project |
| [8.3 Configure a preview URL](/docs/getting-started/tutorial/tutorial-preview-url) | Add a preview button to the Product model content editor sidebar so you can preview draft product pages before publishing |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-frontend-setup"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 8.1 - Set up the frontend starter</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 8.1 - Set up the frontend starter

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-frontend-setup

In this lesson, you will clone the Hygraph Next.js e-commerce starter and install its dependencies. By the end, the starter will be running locally and ready to be connected to your Hygraph project in the next lesson.

<Alert theme="info" title="New to Next.js?">
This lesson clones a pre-built starter. If you want to understand how to create a Next.js project from scratch, see the <Link href="https://nextjs.org/docs" target="_blank">Next.js documentation</Link>. Creating a Next.js app from scratch is out of scope for this tutorial.
</Alert>

## Clone the starter

1. Open your terminal and navigate to the directory where you want the project.
2. Run the following command to clone the starter:

    ```bash
    git clone https://github.com/hygraph/hygraph-next-commerce-starter.git
    ```

3. Navigate into the project directory:

    ```bash
    cd hygraph-next-commerce-starter
    ```

4. Install the package dependencies:

    ```bash
    npm install
    ```

Your project file tree should look like this:

![Next file tree](/images/docs/getting-started/next-file-tree.png)

## What's in the starter

The starter is a Next.js 13 App Router project with Tailwind CSS. Three directories contain the code that powers the storefront:

- **`app/`**: Next.js page components and dynamic routes. The product page at `app/products/[slug]/page.js` and the landing page at `app/[slug]/page.js` are the two routes your Hygraph content populates.

- **`utils/`**: GraphQL query functions. The queries you wrote in lesson 7.1 are used here to fetch content from Hygraph. Each query function maps to a page or component in the `app/` directory.

- **`components/`**: UI components for navigation, product grids, CTAs, landing page sections, and product reviews.

## What's in `.env.sample`

The starter includes a `.env.sample` file in the project root. It contains the three environment variable placeholders you will populate in lessons 8.2 and 8.3:

```bash
HYGRAPH_ENDPOINT=
HYGRAPH_DEV_AUTH_TOKEN=
HYGRAPH_PREVIEW_SECRET=
```

Do not populate these yet. Lesson 8.2 explains what each variable controls and where to find the values.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-connect-storefront"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 8.2 - Connect your storefront</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 6.2 - Localize content

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-localize-content

In this lesson, you will add a Spanish locale to the project and write localized content for the Summer Campaign and the product entries.

While you were building the schema in lesson 1.2, certain fields were marked with the **Localize field** checkbox. Only those fields are available for localization in the content editor. Fields that were not marked are not localizable and display only the default English value. Adding a locale at the project level is what makes the language toggle available at the entry level. Without this step, the Spanish tab does not appear in the content editor.

## Add a locale

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/uUmIbCVsS8GOrwRY8PXj" caption="Add a locale" />

1. Navigate to **Project settings > General > Locales**.
2. Use the dropdown to select **Spanish**.
3. Click **Add**.

The Spanish locale is now added to the project and the language toggle appears in the content editor for all localizable fields.

## Localized content

### Summer Campaign

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/U9vVIrn0QDS8qy9nPbRT" caption="Localize Summer Campaign entry" />

1. Open the **Summer Campaign** landing page entry in the content editor.
2. Under **Localizations**, click **+** next to **Spanish** to add fields for the Spanish locale.
3. Fill in the following localized fields and click **Save & Publish**:

    | Field | Translated content |
    |---|---|
    | Landing page title | Campaña de verano |
    | Stripes > Call to Action > Heading | Prepárate para el verano con estas increíbles ofertas |
    | Stripes > Call to Action > Body | ¡Las rebajas de verano están en pleno apogeo! Mira las increíbles ofertas de verano que tenemos a continuación! |
    | Stripes > Product Grid > Headline | Ropa de verano |

### Products

Repeat the same process for the following product entries:

**Blue running shoes**

| Field | Translated content |
|---|---|
| Product name | Zapatillas para correr azules |
| Product description | Estas zapatillas de running azules ofrecen tanto forma como función, brindando un apoyo excepcional y estilo para tus actividades deportivas. El material transpirable y la suela acolchada garantizan una experiencia cómoda kilómetro tras kilómetro. |

**Plaid shirt**

| Field | Translated content |
|---|---|
| Product name | Camisa a cuadros |
| Product description | Esta camisa a cuadros emana un encanto atemporal, ideal para un día casual fuera o una reunión relajada por la tarde. El patrón clásico a cuadros y el ajuste cómodo la convierten en una prenda básica para un estilo sin esfuerzo. |

**Black leather shoes**

| Field | Translated content |
|---|---|
| Product name | Zapatos de cuero negro |
| Product description | Estos zapatos de cuero negro combinan de manera impecable la sofisticación con la durabilidad, convirtiéndolos en una elección versátil tanto para ocasiones formales como para uso diario. El diseño elegante y el cuero de alta calidad garantizan un atractivo atemporal que complementa cualquier conjunto. |

**Necklace**

| Field | Translated content |
|---|---|
| Product name | Collar |
| Product description | Este collar blanco está elaborado con partes de caracoles de mar, evocando la esencia relajada y playera. Perfecto para quienes buscan un toque marino en su estilo diario. |

**Headband**

| Field | Translated content |
|---|---|
| Product name | Vincha |
| Product description | Esta vincha de algodón blanco brinda un toque elegante y sofisticado a tu peinado. Ideal para completar tu look con un toque de moda y comodidad. |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-content-stages"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 6.3 - Understand content stages</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Full Tutorial - Build Your First eCommerce Project

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-overview

This tutorial takes you through a complete Hygraph project: an e-commerce store selling wearables and home goods. By the end, you will have a working schema, real content, a queryable API, and a connected Next.js storefront.

![Getting started project preview](/images/docs/getting-started/project-preview.png)

Every decision in this tutorial is one you will face on a real project. The schema choices you make in lessons 1 through 5 determine what you can query in lesson 7 and what your frontend renders in lesson 8.

## Choose your path

Your starting point is a cloned Hygraph project. You can choose your own path through the tutorial.

**Option 1: Build from scratch**

This clone includes navigation structure and image assets. You will build the schema, content, API configuration, and frontend connection yourself, step by step.

Choose this path if you want to understand how every part of a Hygraph project is constructed and why.

**Requirements**

- <Link href="https://app.hygraph.com/signup" target="_blank">Hygraph account</Link>
- Basic <Link href="https://hygraph.com/learn/graphql" target="_blank">GraphQL knowledge</Link>
- Basic understanding of [content modeling](/docs/core-concepts/content-modeling/content-modeling-overview)
- Code editor, such as VS Code
- Current version of <Link href="https://nodejs.org/" target="_blank">Node.js</Link>
- Netlify or Vercel account (required for lessons 8 and 9)
- Growth plan or higher, or a [30-day trial](/docs/getting-started/update-billing), for lessons 5.1 through 5.3

<Button
  href="https://app.hygraph.com/clone/d7dbfb8e7f6845ba80749e3822a6484a?name=eCommerce%20Tutorial%20-%20Option%201"
  size="md"
  variant="solid"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Select Option 1</Button>

**Option 2: Explore a complete project**

This clone includes the complete Hygraph project: all models, components, enumerations, content entries, and localized content already built. You will skip straight to querying and frontend connection.

Choose this path if you want to practice API queries, mutations, and frontend integration without building the schema yourself.

**Requirements**

- <Link href="https://app.hygraph.com/signup" target="_blank">Hygraph account</Link>
- Basic <Link href="https://hygraph.com/learn/graphql" target="_blank">GraphQL knowledge</Link>
- Basic understanding of [content modeling](/docs/core-concepts/content-modeling/content-modeling-overview)
- Growth plan or higher, or a [30-day trial](/docs/getting-started/update-billing), for remote sources

<Button 
  href="https://app.hygraph.com/clone/4d65d295cd1e4912aa401fb15f72d40d?name=eCommerce%20Tutorial%20-%20Option%202"
  size="md"
  variant="solid"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Select Option 2</Button> 

## Clone the project

The cloning process is the same for both options.

![Clone project screen](/images/docs/getting-started/clone-project-screen.png)

The project already has a name, but you can give it a new name. You can also optionally add a description, select a region, and click **Clone now**. Cloning takes a couple of minutes. When it finishes, you land on your project homepage.

## What's already in your project

<Alert theme="info" title="Option 2 readers">
This section is for Option 2 readers only. If you chose Option 1, move on to the lesson overview below.
</Alert>

Your cloned project is fully built. Here is what it contains.

**Schema**

| Type | What's included |
|---|---|
| Models | Product, Product category, Blog post, Seller information, Landing page, Navigation |
| Components | Related Products, Product variant, Clothing, Shoes, Accessories, Decor, Button, Call to Action, Product Grid, Link |
| Enumerations | Clothes size, Shoes size, Wearable items color, Decor items color |
| Remote source | HyDemoAPI, a Hygraph-maintained REST API used to fetch product reviews |
| Remote fields | Reviews field on the Product model; Reviews top-level field on the Query model |

**Content**

| Type | What's included |
|---|---|
| Products | 9 published entries with images, variants, related products, and category assignments |
| Product categories | 7 published entries |
| Landing pages | Homepage and Summer Campaign, both with localized Spanish content |
| Navigation | Main navigation with category and campaign links |
| Seller information | 1 published entry |
| Assets | All product images with alt text and captions |

<Alert theme="warning" title="What is not included">
Your project does not include API tokens, environment variable configuration, a connected frontend, or webhooks. You will set those up in lessons 8 and 9.
</Alert>

**Your path through the tutorial**

1. Query your content in the API Playground.
2. Run mutations.
3. Set up the Next.js frontend starter.
4. Connect Hygraph to your local frontend.
5. Configure a preview URL for draft content.
6. Set up a webhook to trigger frontend deploys on publish.

## Lesson overview

<Alert theme="info">
The full lesson sequence is below. Option 2 readers start at [lesson 7.1](/docs/getting-started/tutorial/tutorial-write-queries).
</Alert>

### Lesson 1 — Content models

| # | Lesson | What you will be able to do |
|---|---|---|
| 1.1 | [Design your content models](/docs/getting-started/tutorial/tutorial-design-content-models) | Sketch your model structure and understand how fields, models, and schema relate to each other |
| 1.2 | [Build your content models](/docs/getting-started/tutorial/tutorial-build-content-models) | Create your base models and fields in the Hygraph schema editor |

### Lesson 2 — References

| # | Lesson | What you will be able to do |
|---|---|---|
| 2.1 | [Configure reference fields](/docs/getting-started/tutorial/tutorial-configure-reference-fields) | Connect models to each other using one-to-one, one-to-many, and many-to-many references |

### Lesson 3 — Enumerations

| # | Lesson | What you will be able to do |
|---|---|---|
| 3.1 | [Configure enumerations](/docs/getting-started/tutorial/tutorial-configure-enumerations) | Create predefined value sets that appear as dropdowns in the content editor |

### Lesson 4 — Components

| # | Lesson | What you will be able to do |
|---|---|---|
| 4.1 | [Build components](/docs/getting-started/tutorial/tutorial-build-components) | Create reusable field sets for product variants, CTAs, related products, and navigation links |
| 4.2 | [Add components to your models](/docs/getting-started/tutorial/tutorial-add-components-to-models) | Attach your components to models as basic and modular component fields |

### Lesson 5 — Remote Sources

| # | Lesson | What you will be able to do |
|---|---|---|
| 5.1 | [Add a Remote Source](/docs/getting-started/tutorial/tutorial-add-remote-source) | Connect an external REST API to your Hygraph schema |
| 5.2 | [Remote Fields](/docs/getting-started/tutorial/tutorial-add-remote-fields) | Fetch remote data within the context of a specific model entry |
| 5.3 | [Top-level Remote Fields](/docs/getting-started/tutorial/tutorial-add-top-level-remote-fields) | Fetch remote data outside the context of any model and serve it alongside Hygraph content in a single API call |

### Lesson 6 — The Content Editor

| # | Lesson | What you will be able to do |
|---|---|---|
| 6.1 | [Create content](/docs/getting-started/tutorial/tutorial-create-content) | Create and publish products, categories, landing pages, and navigation entries |
| 6.2 | [Localize content](/docs/getting-started/tutorial/tutorial-localize-content) | Add a locale and write localized content for selected fields |
| 6.3 | [Understand content stages](/docs/getting-started/tutorial/tutorial-content-stages) | Learn how `DRAFT` and `PUBLISHED` content stages affect what the Content API returns and what the frontend displays |

### Lesson 7 — The API Playground

| # | Lesson | What you will be able to do |
|---|---|---|
| 7.1 | [Exercises: Queries](/docs/getting-started/tutorial/tutorial-write-queries) | Write queries for models, references, components, and remote fields |
| 7.2 | [Exercises: Mutations](/docs/getting-started/tutorial/tutorial-write-mutations) | Create, update, publish, and delete content entries programmatically |

### Lesson 8 — Frontend Connection

| # | Lesson | What you will be able to do |
|---|---|---|
| 8.1 | [Set up the frontend starter](/docs/getting-started/tutorial/tutorial-frontend-setup) | Clone and configure the Next.js e-commerce starter locally |
| 8.2 | [Connect your storefront](/docs/getting-started/tutorial/tutorial-connect-storefront) | Configure API access permissions, create a PAT, and connect Hygraph to your local frontend |
| 8.3 | [Preview URL](/docs/getting-started/tutorial/tutorial-preview-url) | Add a preview button to the content editor sidebar to preview draft content before publishing |

### Lesson 9 — Webhooks

| # | Lesson | What you will be able to do |
|---|---|---|
| 9.1 | [Configure webhooks](/docs/getting-started/tutorial/tutorial-configure-webhooks) | Set up a webhook that triggers a frontend rebuild whenever content is published |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-content-models-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Build from scratch</Button>
OR
<Button
  href="/docs/getting-started/tutorial/tutorial-queries-mutations-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Explore a complete project</Button>

---
# Lesson 8.3 - Configure a preview URL

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-preview-url

In this lesson, you will configure a preview URL for the `Product` model. Once configured, every product entry in the content editor displays an **Open live preview** button in its sidebar. Clicking it opens a preview of that product page in your local frontend using the draft content token configured in lesson 8.2.

The preview URL uses a secret key to prevent unauthorized access to draft content. Only requests that include the correct secret can trigger a draft preview. Generate a strong secret and do not commit it to version control.

## Configure the preview URL

1. Navigate to the **Schema** and select the **Product** model.
2. Click the **Sidebar** tab.
3. Select the **Preview** widget.
4. Provide the following details:
    - **Preview Name**: Product preview
    - **URL template**: `http://localhost:3000/api/draft?slug={productSlug}&model=products&secret=YOUR_SECRET_HERE`

    `{productSlug}` is handlebars notation. Hygraph replaces it with the `productSlug` field value of the entry being previewed. The API ID `productSlug` was set when you created the Product Slug field in lesson 1.2. 

5. Click **Save**.

## Add the preview secret

1. Generate a secret key using a key generator of your choice. Use a strong random string.
2. Replace `YOUR_SECRET_HERE` in the URL template with the generated secret.
3. Open `.env.local` and add the secret as `HYGRAPH_PREVIEW_SECRET`:

    ```bash
    HYGRAPH_PREVIEW_SECRET=YOUR_SECRET_HERE
    ```

4. Restart the local development server to load the new environment variable:

    ```bash
    npm run dev
    ```

## Your complete `.env.local`

At this point, all three environment variables should be populated. Your `.env.local` file should look like this:

```bash
HYGRAPH_ENDPOINT=YOUR_CONTENT_API_ENDPOINT_HERE
HYGRAPH_DEV_AUTH_TOKEN=YOUR_DRAFT_TOKEN_HERE
HYGRAPH_PREVIEW_SECRET=YOUR_SECRET_HERE
```

If any of the three are missing or incorrect, the preview will not work.

## Verify the preview URL

1. Navigate to the **Content editor** and open any product entry.
2. Click **Open live preview**. 

    The product page should open in a new browser tab at `http://localhost:3000` showing the draft version of that product.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-webhooks-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 9 - Webhooks</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 7 - Queries and mutations

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-queries-mutations-overview

This section covers querying and mutating content in the Hygraph API Playground.

The API Playground is not a demo environment. It queries the same Content API your frontend will use in lesson 8. Every query you run here returns real data from your project, and every mutation makes a real change. The patterns practiced in these two lessons are the same ones your frontend code will use.

The exercises are structured in the same order the schema was built: basic model queries first, then references, then components, then remote data. If a query returns unexpected results, it is a signal about the schema or content, not a problem with the query itself.

By the end of lesson 7.2, you will have:

- Queried all major schema features: models, references, components, remote fields, and top-level remote fields
- Created, updated, published, unpublished, and deleted a product entry programmatically
- Confirmed that every schema decision made in lessons 1 through 5 is reflected in the API

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [7.1 Write queries](/docs/getting-started/tutorial/tutorial-write-queries) | Run queries for models, references, components, remote fields, and top-level remote fields in the API Playground |
| [7.2 Write mutations](/docs/getting-started/tutorial/tutorial-write-mutations) | Create, update, publish, unpublish, and delete a product entry programmatically using the Product model mutations |

For the complete Content API reference, see [Queries](/docs/api-reference/content-api/queries) and [Mutations](/docs/api-reference/content-api/mutations).

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-write-queries"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 7.1 - Write queries</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 2 - References

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-references-overview

This section covers adding reference fields to the models built in lesson 1.2.

References connect models to each other. The connections you configure here are what make it possible to query a product and receive its categories in a single API call.

Without references, a product entry has no connection to its categories, and a landing page has no connection to its blog posts. This is why references are a critical part of the schema.

By the end of lesson 2.1, the following model relationships are configured:

- Products connected to Product categories (many-to-many, two-way)
- Landing page connected to Blog posts, Product categories, and Seller information (one-way)

## How references work

The way you configure reference fields determines the following:

**Type** controls which models can be referenced. Selecting a single model means only that model's entries can be connected. Selecting multiple models creates a union reference.

**Direction** controls which side of the relationship can be queried. A one-way reference allows querying only from the model where the field lives. A two-way reference adds a reverse field to the referenced model, so you can query from either side.

**Cardinality** controls how many entries can be connected. The combination of direction and cardinality produces four reference patterns:

| Pattern | What it means | When to use it |
|---|---|---|
| One-to-one | One entry connects to one entry | A landing page linked to one seller information entry |
| One-to-many | One entry connects to many entries | A landing page linked to multiple blog posts |
| Many-to-many | Many entries connect to many entries | Products assigned to multiple categories |
| Many-to-one | Many entries connect to one entry | Multiple landing pages linked to one seller information entry |

The references created in this lesson impact the queries in lesson 7.

For the complete reference field documentation, see [References](/docs/developer-guides/schema/references).

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [2.1 Configure reference fields](/docs/getting-started/tutorial/tutorial-configure-reference-fields) | Add reference fields to the `Product` and `Landing page` models and configure their type, direction, and cardinality |

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-configure-reference-fields"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 2.1 - Configure reference fields</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.

---
# Lesson 5 - Remote sources

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-remote-sources-overview

This section covers connecting the e-commerce project to an external REST API and making its data queryable through the Hygraph API alongside native Hygraph content.

<Alert theme="info" title="Plan requirement">
Remote sources require a Growth plan or higher, or a [30-day trial](/docs/getting-started/update-billing).
</Alert>

Without this section, the schema can only return data stored in Hygraph. After completing the lessons in this section, a single API call to Hygraph returns both Hygraph content and external review data. No separate API request is needed, and no data is migrated or duplicated.

The three lessons build on each other in sequence. The remote source must exist before adding remote fields. Remote fields must exist before the top-level remote field can be tested against real data.

By the end of lesson 5.3, the project schema includes:

- A REST remote source connected to the Hygraph demo API (`HyDemoAPI`)
- A remote field on the `Product` model that fetches reviews scoped to each product entry
- A top-level remote field on the `Query` model that fetches reviews independently of any product entry

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [5.1 Add a remote source](/docs/getting-started/tutorial/tutorial-add-remote-source) | Connect the HyDemoAPI REST endpoint to the project schema and define the custom types Hygraph needs to query it |
| [5.2 Add remote fields](/docs/getting-started/tutorial/tutorial-add-remote-fields) | Add a remote field to the `Product` model to fetch review data scoped to each product entry |
| [5.3 Add top-level remote fields](/docs/getting-started/tutorial/tutorial-add-top-level-remote-fields) | Add a top-level remote field to the `Query` model and run a test query to confirm the remote source is working |

For the complete remote sources documentation, see [Remote Sources](/docs/developer-guides/remote-data/overview).

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-add-remote-source"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 5.1 - Add a remote source</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 9 - Webhooks

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-webhooks-overview

This section covers configuring a webhook that keeps the deployed storefront in sync with published content.

A deployed storefront is a static build created at a specific point in time. When you publish content in Hygraph, the live site does not automatically update. Setting up a webhook closes that gap. When content moves to the `PUBLISHED` stage, Hygraph sends a POST request to a build hook URL on your deployment platform, which triggers a new build and deploys the latest published content.

By the end of lesson 9.1, every time content is published in your Hygraph project, the storefront automatically rebuilds and deploys.

## Lessons in this section

| Lesson | What you will do |
|---|---|
| [9.1 Configure webhooks](/docs/getting-started/tutorial/tutorial-configure-webhooks) | Create a webhook in Hygraph that sends a build trigger to Netlify or Vercel whenever content is published |

For the complete webhooks documentation, see [Webhooks](/docs/developer-guides/webhooks/webhooks-overview).

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-configure-webhooks"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 9.1 - Configure webhooks</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Wrap-up

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-wrap-up

You built a complete, deployed e-commerce website backed by Hygraph. The schema, content, API, storefront, preview configuration, and deployment automation you configured in this tutorial are the same patterns used in production Hygraph projects.

## What you can now do

**Design a content architecture from business goals.**
You started with four store requirements: product listings, categories, landing pages, and reviews, and translated them into a schema of models, components, enumerations, and remote sources. You can apply this planning process to any content-driven project.

**Build a schema in layers.**
You built the schema across four sections: models, references, components, and remote sources, because models are interconnected and some connections can only be made after their dependencies exist. This layered approach applies to any Hygraph project regardless of complexity.

**Use Content Federation to query external data.**
You connected an external REST API to the Hygraph schema using a remote source, added a remote field scoped to individual product entries, and added a top-level remote field that returns external data independently of any content entry. A single API call now returns Hygraph content and external review data together.

**Query and mutate content programmatically.**
You wrote queries for models, references, modular components, and remote fields using the Hygraph API Playground. You created, updated, published, unpublished, and deleted a content entry using mutations. These are the same operations your frontend uses.

**Connect a Next.js frontend to Hygraph.**
You configured Content API permissions, created a PAT for draft content access, connected a Next.js project using environment variables, and confirmed published content renders in the browser.

**Automate deployments on publish.**
You configured a webhook that sends a POST request to your deployment platform whenever a `Product` entry is published, triggering an automatic rebuild without manual intervention.

## Best practices

**Start with business goals, not schema fields.**
The models in this tutorial came from four store requirements, not from a list of fields someone wanted to store. Knowing what the store must do is what determined the schema structure.

**Name models and fields for collaborators, not for yourself.**
API IDs like `productSlug`, `categoryName`, and `businessDescription` are readable by any developer or editor who joins the project later. Ambiguous names like `field1` or `titleText` create friction that compounds over time.

**Build schemas in layers.**
Models are interconnected. Build base models first, then references, then components, then remote fields. Trying to configure everything at once leads to circular dependencies and incomplete field definitions.

**Localize at the schema level, not as an afterthought.**
Deciding which fields need localization at schema design time is cheaper than restructuring later.

## What to build next

Before going deeper on any specific Hygraph feature, consider adding an SEO component to your project. It is something every production project needs.

| Field | Type | Notes |
|---|---|---|
| SEO title | Single line text | Overrides the page title in search results |
| SEO description | Single line text | Appears under the page title in search results |
| SEO image | Asset picker | Cover image for social sharing. Use a named, compressed image with clear alt text. |
| Canonical URL | Slug | Leave blank to default to the page URL. Prevents duplicate content penalties. |

Attach the SEO component to the `Product`, `Landing page`, and `Blog post` models using a basic component field. 

## Continue your learning

### Schema and content modeling

| Resource | What it covers |
|---|---|
| [Content modeling](/docs/core-concepts/content-modeling/content-modeling-in-hygraph) | The full theory behind content modeling in Hygraph: models, fields, scalars, and system artifacts |
| [Components](/docs/developer-guides/schema/components) | Component types, nested components, copy/paste, the 50-instance UI limit, and querying |
| [Components or references?](/docs/developer-guides/schema/components-or-references) | How to decide between a component field and a reference field |
| [References](/docs/developer-guides/schema/references) | All reference types, directions, and cardinality options |
| [Enumerations](/docs/developer-guides/schema/using-enumerations) | Enumeration configuration and API behavior |
| [Taxonomies](/docs/developer-guides/schema/taxonomies) | Hierarchical classification structures and the `descendants_of` filter |
| [Field types](/docs/api-reference/schema/field-types) | API reference for all field types, input types, and filter options |
| [Field configuration](/docs/api-reference/schema/field-configuration) | Settings, validations, and advanced options for every field |

### API and content operations

| Resource | What it covers |
|---|---|
| [Queries](/docs/api-reference/content-api/queries) | Full query reference: filters, pagination, ordering, and localization |
| [Mutations](/docs/api-reference/content-api/mutations) | Full mutation reference: create, update, publish, unpublish, delete |
| [Content stages](/docs/api-reference/content-api/content-stages) | Default and custom content stages, and how to use them in workflows |
| [Content localization](/docs/api-reference/content-api/localization) | Full localization reference beyond what the tutorial covers |
| [Assets](/docs/api-reference/assets/assets-overview) | Asset upload, management, and transformations |
| [Remote Sources](/docs/developer-guides/remote-data/overview) | Full reference for remote sources, remote fields, and top-level remote fields |

### Deployment and automation

| Resource | What it covers |
|---|---|
| [Webhooks](/docs/developer-guides/webhooks/webhooks-overview) | Webhook configuration, triggers, logs, and retry behavior |
| [Deploy to Vercel with webhooks](/docs/developer-guides/webhooks/trigger-static-build) | Step-by-step Vercel deployment automation |
| [Hygraph-Netlify integration](/docs/integrations/connect-netlify) | Manual redeploy button and deployment status indicator in the content editor |
| [Content Workflows](/docs/developer-guides/project/content-workflows) | Custom review and approval workflows between DRAFT and PUBLISHED |

---
# Lesson 7.2 - Write mutations

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-write-mutations

In this lesson, you will use mutations to create, update, publish, unpublish, and delete a product entry. The mutations follow a complete content lifecycle: create it, change it, publish it, unpublish it, remove it. After each destructive mutation, you will run a quick query to confirm the change took effect.

Running a verification query after a mutation is not just a tutorial step. It is the correct practice for any destructive or state-changing API operation.

Hygraph automatically generates five mutations for each model when it is created. For the Product model, those are `createProduct`, `updateProduct`, `publishProduct`, `unpublishProduct`, and `deleteProduct`. They are used here in lifecycle order.

## `createProduct`

This mutation creates a new product entry with a name, slug, price, product variant, related product, category assignment, and a placeholder image asset.

<Tabs panelHeight={600}>
  <TabsItem label="Mutation">

```graphql
mutation MyMutation {
  createProduct(
    data: {
      productName: "My latest product"
      productSlug: "my-latest-product"
      productPrice: 59.99
      productVariant: {
        create: {
          productType: { create: { Clothing: { size: M, color: Green } } }
        }
      }
      relatedProducts: {
        create: {
          title: "Related Products"
          products: { connect: { productSlug: "plaid-shirt" } }
        }
      }
      productCategories: { connect: { slug: "clothes" } }
      productImage: { create: { handle: "", fileName: "" } }
    }
  ) {
    productName
    productPrice
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "createProduct": {
      "productName": "My latest product",
      "productPrice": 59.99
    }
  }
}
```

  </TabsItem>
</Tabs>

The mutation uses nested `create` blocks to configure the product variant and related products inline. The `products` connect uses `plaid-shirt`, one of the five core products from lesson 6.1. The `productCategories` field uses `connect` to link to an existing category entry rather than creating a new one.

Open the **Content editor** and navigate to the **Product** model. The new entry appears there in the `DRAFT` stage.

![createProduct mutation result in the content editor](/images/docs/getting-started/createproduct-mutations-example.png)

## `updateProduct`

This mutation changes the `productName` of the entry created above. The `where` clause uses `productSlug` as the unique identifier because it was configured to be unique in lesson 1.2.

<Tabs panelHeight={300}>
  <TabsItem label="Mutation">

```graphql
mutation MyMutation {
  updateProduct(
    data: { productName: "Updated Product" }
    where: { productSlug: "my-latest-product" }
  ) {
    productSlug
    productName
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "updateProduct": {
      "productSlug": "my-latest-product",
      "productName": "Updated Product"
    }
  }
}
```

  </TabsItem>
</Tabs>

![updateProduct mutation result](/images/docs/getting-started/updateproduct-mutations-example1.png)

The `updateProduct` mutation works on any entry, not only newly created ones. To demonstrate, update the Black leather shoes entry:

<Tabs panelHeight={300}>
  <TabsItem label="Mutation">

```graphql
mutation MyMutation {
  updateProduct(
    data: { productName: "My black leather shoes" }
    where: { productSlug: "black-leather-shoes" }
  ) {
    productSlug
    productName
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "updateProduct": {
      "productSlug": "black-leather-shoes",
      "productName": "My black leather shoes"
    }
  }
}
```

  </TabsItem>
</Tabs>

![updateProduct mutation second example](/images/docs/getting-started/updateproduct-mutations-example2.png)

## `publishProduct`

The entry created above is in `DRAFT`. This mutation promotes it to `PUBLISHED` so it is visible when querying the `PUBLISHED` stage.

![Entry in DRAFT stage before publishing](/images/docs/getting-started/publishProduct-mutations-draftmode.png)

<Tabs panelHeight={300}>
  <TabsItem label="Mutation">

```graphql
mutation MyMutation {
  publishProduct(where: { productSlug: "my-latest-product" }, to: PUBLISHED) {
    stage
    productName
  }
}
```

  </TabsItem>
</Tabs>

Open the content editor to confirm the entry is now published.

![Entry in PUBLISHED stage after publishing](/images/docs/getting-started/publishProduct-mutations-publishedmode.png)

## `unpublishProduct`

<Alert theme="info" title="Optional">
This step is optional. Skip to `deleteProduct` to continue the lifecycle.
</Alert>

This mutation returns the entry to `DRAFT` only.

<Tabs panelHeight={300}>
  <TabsItem label="Mutation">

```graphql
mutation MyMutation {
  unpublishProduct(
    where: { productSlug: "my-latest-product" }
    from: PUBLISHED
  ) {
    stage
    productName
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "unpublishProduct": {
      "stage": "DRAFT",
      "productName": "Updated Product"
    }
  }
}
```

  </TabsItem>
</Tabs>

![Entry returned to DRAFT after unpublishing](/images/docs/getting-started/publishProduct-mutations-draftmode2.png)

## `deleteProduct`

This mutation permanently deletes the entry. Deletion cannot be undone.

<Tabs panelHeight={200}>
  <TabsItem label="Mutation">

```graphql
mutation DeleteMutation {
  deleteProduct(where: { productSlug: "my-latest-product" }) {
    productName
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "deleteProduct": {
      "productName": "Updated Product"
    }
  }
}
```

  </TabsItem>
</Tabs>

## Verify the deletion

Run this query to confirm the entry no longer exists.

<Tabs panelHeight={200}>
  <TabsItem label="Query">

```graphql
query CheckDeletion {
  products {
    productName
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      { "productName": "My black leather shoes" },
      { "productName": "Blue running shoes" },
      { "productName": "Plaid shirt" },
      { "productName": "Necklace" },
      { "productName": "Headband" }
    ]
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="info" title="Response varies by content">
Your response reflects only the product entries you created. If you completed the additional practice in lesson 6.1, more entries will appear. The Black leather shoes entry may show the updated name "My black leather shoes" from the updateProduct mutation above.
</Alert>

The deleted entry does not appear. This verify-after-mutate pattern applies to any mutation in any project. Run a query immediately after a destructive operation to confirm the result.

The project now has a queryable API, published content, and a confirmed remote source connection. The next step is connecting a frontend to display this content in a storefront.

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-frontend-overview"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 8 - Frontend</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Lesson 7.1 - Write queries

Source: https://hygraph.com/docs/getting-started/tutorial/tutorial-write-queries

In this lesson, you will run queries against the project's Content API in the API Playground. The exercises follow the same order the schema was built: basic model queries first, then references, then components, then remote data. Each exercise proves that a specific set of schema decisions works as configured.

Navigate to the **API Playground** in your project sidebar to get started.

## How queries are generated

Hygraph automatically generates queries for each model when it is created. Two queries are generated per model, named after the model's **API ID** and **Plural API ID**. The API ID fetches a single entry. The Plural API ID fetches multiple entries.

The **Product category** model is a good example. In the API Playground tree, `productCategory` fetches one category entry and `productCategories` fetches all of them. Expanding `productCategories` in the tree shows all the fields added to the model: `categoryName`, `slug`, `description`, and `products`.

![API Playground with displayed tree](/images/docs/getting-started/api-playground-tree-displayed.png)

Queries can be built by selecting fields in the tree or typed manually. All exercises below can be copied and pasted directly into the API Playground.

## GraphQL 1

This query fetches all product categories. The Plural API ID `productCategories` returns multiple entries.

<Tabs panelHeight={240}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  productCategories {
    categoryName
    description {
      text
    }
    slug
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "productCategories": [
      {
        "categoryName": "Clothes",
        "description": {
          "text": "You will find clothes here"
        },
        "slug": "clothes"
      },
      {
        "categoryName": "Shoes",
        "description": {
          "text": "You will find shoes here"
        },
        "slug": "shoes"
      },
      {
        "categoryName": "Sportswear",
        "description": {
          "text": "You will find sportswear here"
        },
        "slug": "sportswear"
      },
      {
        "categoryName": "Urban",
        "description": {
          "text": "You will find urban-style items here"
        },
        "slug": "urban"
      },
      {
        "categoryName": "New arrival",
        "description": {
          "text": "You will find our latest arrivals here"
        },
        "slug": "new-arrival"
      },
      {
        "categoryName": "Decor",
        "description": {
          "text": "You will find decor items here"
        },
        "slug": "decor"
      },
      {
        "categoryName": "Accessories",
        "description": {
          "text": "You will find accessories here"
        },
        "slug": "accessories"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The `description` field uses `text` as the output format because it was added as a Rich Text field in lesson 1.2. Rich Text fields require an explicit output format — `text`, `html`, `markdown`, or `raw`. Omitting the format returns an error.

## GraphQL 2

This query fetches all products in the **New arrival** category using a `where` filter on the category `slug`.

<Tabs panelHeight={200}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  productCategory(where: { slug: "new-arrival" }) {
    products {
      productName
      productSlug
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "productCategory": {
      "products": [
        {
          "productName": "Colorful socks",
          "productSlug": "colorful-socks"
        },
        {
          "productName": "Green Hoodie",
          "productSlug": "green-hoodie"
        },
        {
          "productName": "Plaid shirt",
          "productSlug": "plaid-shirt"
        },
        {
          "productName": "Black leather shoes",
          "productSlug": "black-leather-shoes"
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

The `products` field is queryable here because of the two-way many-to-many reference configured in lesson 2.1. The two-way direction is what makes it possible to navigate from a category to its products.

<Alert theme="info" title="Response varies by content">
Your response may differ depending on whether you completed the additional practice entries in lesson 6.1. Entries that were not created cannot be returned.
</Alert>

## GraphQL 3

**Try this yourself:** Find the `productName` and `productSlug` of all products in the `urban` category.

<Tabs panelHeight={200}>
  <TabsItem label="Solution">

```graphql
query MyQuery {
  productCategory(where: { slug: "urban" }) {
    products {
      productName
      productSlug
    }
  }
}
```

  </TabsItem>
</Tabs>

## References 1

This query fetches the related products connected to the plaid shirt entry. The `relatedProducts` field is a basic component field added to the `Product` model in lesson 4.2. The component contains a `title` field and a `products` reference field.

<Tabs panelHeight={280}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  product(where: { productSlug: "plaid-shirt" }) {
    relatedProducts {
      title
      products {
        productName
        productSlug
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "product": {
      "relatedProducts": {
        "title": "Related Products",
        "products": [
          {
            "productName": "Black leather shoes",
            "productSlug": "black-leather-shoes"
          },
          {
            "productName": "Blue running shoes",
            "productSlug": "blue-running-shoes"
          },
          {
            "productName": "Headband",
            "productSlug": "headband"
          },
          {
            "productName": "Necklace",
            "productSlug": "necklace"
          }
        ]
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

The `title` field returns `Related Products` for every entry because it was configured as a read-only field with a fixed initial value in lesson 4.1.

## References 2

This query fetches all products in the `sportswear` category along with their product descriptions in HTML format.

<Tabs panelHeight={280}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  productCategory(where: { slug: "sportswear" }) {
    products {
      productName
      productSlug
      productDescription {
        html
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "productCategory": {
      "products": [
        {
          "productName": "Green Hoodie",
          "productSlug": "green-hoodie",
          "productDescription": {
            "html": "<p>This green hoodie combines comfort and style seamlessly, making it your go-to choice for a casual yet trendy look. Its soft fabric and versatile shade of green make it a wardrobe essential for all seasons.</p>"
          }
        },
        {
          "productName": "Blue running shoes",
          "productSlug": "blue-running-shoes",
          "productDescription": {
            "html": "<p>These blue running shoes offer both form and function, providing exceptional support and style for your active pursuits. The breathable material and cushioned sole ensure a comfortable experience mile after mile.</p>"
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

This response requires the additional practice entries from lesson 6.1. If you only created the core five products, Sportswear may return fewer results.

![Items in the sportswear category](/images/docs/getting-started/product-category-contents-example.png)

## References 3

**Try this yourself:** Query the `sellerInformation` reference on the homepage landing page entry. Find out the `businessName` and `businessDescription`.

<Tabs panelHeight={220}>
  <TabsItem label="Solution">

```graphql
query MyQuery {
  landingPage(where: { link: "/" }) {
    sellerInformation {
      businessName
      businessDescription {
        text
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Components 1

This query fetches the `productVariant` component for the headband entry. Because `productType` is a modular component field, the query uses an inline fragment (`... on Accessory`) to specify which component type to query and which fields to return from it.

<Tabs panelHeight={420}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  product(where: { productSlug: "headband" }) {
    productName
    productDescription {
      html
    }
    productVariant {
      productType {
        ... on Accessory {
          color
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "product": {
      "productName": "Headband",
      "productDescription": {
        "html": "<p>This white cotton headband provides an elegant and sophisticated touch to your hairstyle. Perfect for completing your look with a blend of fashion and comfort.</p>"
      },
      "productVariant": {
        "productType": {
          "color": "White"
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

Inline fragments are required for modular component fields because the API needs to know which component type's fields to return. You can include multiple inline fragments in the same query to handle all possible component types simultaneously. For example, `... on Clothing { size color }` alongside `... on Accessory { color }`.

## Components 2

This query fetches the `relatedProducts` component for the blue running shoes entry, returning product descriptions in HTML format.

<Tabs panelHeight={390}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  product(where: { productSlug: "blue-running-shoes" }) {
    productName
    productDescription {
      html
    }
    relatedProducts {
      products {
        productDescription {
          html
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "product": {
      "productName": "Blue running shoes",
      "productDescription": {
        "html": "<p>These blue running shoes offer both form and function, providing exceptional support and style for your active pursuits. The breathable material and cushioned sole ensure a comfortable experience mile after mile.</p>"
      },
      "relatedProducts": {
        "products": [
          {
            "productDescription": {
              "html": "<p>These black leather shoes seamlessly blend sophistication with durability, making them a versatile choice for both formal occasions and everyday wear. The sleek design and high-quality leather ensure a timeless appeal that complements any outfit.</p>"
            }
          },
          {
            "productDescription": {
              "html": "<p>This white necklace is crafted from parts of seashells, evoking a relaxed, beachy vibe. Perfect for those looking to add a touch of the sea to their daily style.</p>"
            }
          },
          {
            "productDescription": {
              "html": "<p>This white cotton headband provides an elegant and sophisticated touch to your hairstyle. Perfect for completing your look with a blend of fashion and comfort.</p>"
            }
          },
          {
            "productDescription": {
              "html": "<p>This plaid shirt exudes a timeless charm, perfect for a casual day out or a relaxed evening gathering. The classic checkered pattern and comfortable fit make it a wardrobe staple for effortless style.</p>"
            }
          }
        ]
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Components 3

This query filters all products by a value inside the `productVariant` modular component, specifically all Accessory type products where the color is White.

<Tabs panelHeight={290}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  products(
    where: { productVariant: { productType: { Accessory: { color: White } } } }
  ) {
    productName
    productSlug
    productDescription {
      html
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "productName": "Necklace",
        "productSlug": "necklace",
        "productDescription": {
          "html": "<p>This white necklace is crafted from parts of seashells, evoking a relaxed, beachy vibe. Perfect for those looking to add a touch of the sea to their daily style.</p>"
        }
      },
      {
        "productName": "Headband",
        "productSlug": "headband",
        "productDescription": {
          "html": "<p>This white cotton headband provides an elegant and sophisticated touch to your hairstyle. Perfect for completing your look with a blend of fashion and comfort.</p>"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

Filtering on a modular component field uses the component type name (`Accessory`) as a nested key in the `where` clause. The same pattern applies to `Clothing`, `Shoes`, and `Decor`.

## Components 4

**Try this yourself:** Query the `stripes` modular component inside the homepage landing page entry. Find the `productName` and `productSlug` of all products added to the Product Grid section.

<Tabs panelHeight={260}>
  <TabsItem label="Solution">

```graphql
query MyQuery {
  landingPage(where: { link: "/" }) {
    stripes {
      ... on ProductGrid {
        headline
        products {
          productName
          productSlug
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Remote Fields 1

This query fetches all products and their reviews from the remote field configured in lesson 5.2. The `reviews` field lives on the Product model and returns data from the HyDemoAPI remote source scoped to each product's slug.

<Tabs panelHeight={290}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  products {
    reviews {
      data {
        name
        comment
        rating
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "reviews": {
          "data": [
            {
              "name": "Sock Lover",
              "comment": "These socks are great. They are very colorful and they keep my feet warm.",
              "rating": 4.5
            }
          ]
        }
      },
      {
        "reviews": {
          "data": [
            {
              "name": "Green Fan",
              "comment": "This is the absolute best hoodie I've ever had",
              "rating": 5
            }
          ]
        }
      },
      {
        "reviews": {
          "data": [
            {
              "name": "Runner in Rochester",
              "comment": "These shoes are great. I've run 100 miles in them and they are still in great shape.",
              "rating": 5
            }
          ]
        }
      },
      {
        "reviews": {
          "data": []
        }
      },
      {
        "reviews": {
          "data": [
            {
              "name": "Oregon Person",
              "comment": "After wearing this shirt for 2 days, I realized it was made of cotton. I am allergic to cotton. I am very disappointed.",
              "rating": 1.5
            },
            {
              "name": "Another Person",
              "comment": "This shirt is okay. It lost a button, but I sewed it back on.",
              "rating": 3.5
            },
            {
              "name": "Third Person",
              "comment": "I love this shirt. I wear it all the time.",
              "rating": 4.5
            }
          ]
        }
      },
      {
        "reviews": {
          "data": [
            {
              "name": "First Person",
              "comment": "These shoes are both the most comfortable and the most stylish I have ever owned.",
              "rating": 4.5
            },
            {
              "name": "Second Person",
              "comment": "These would be better if they were red.",
              "rating": 2.5
            },
            {
              "name": "Third Person",
              "comment": "I've worn these for 3 years and they are still in great shape.",
              "rating": 4.5
            }
          ]
        }
      },
      {
        "reviews": {
          "data": []
        }
      },
      {
        "reviews": {
          "data": []
        }
      },
      {
        "reviews": {
          "data": []
        }
      },
      {
        "reviews": {
          "data": []
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

Some products return an empty `data` array. This is expected because the HyDemoAPI only contains reviews for products whose slugs match entries in its dataset. Products with no matching reviews return an empty array, not an error.

## Remote Fields 2

This query fetches reviews scoped to a single product, the plaid shirt, using a `where` filter on `productSlug`. The remote field path uses `{{doc.productSlug}}` as the argument, so only reviews for that specific slug are returned.

<Tabs panelHeight={350}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  product(where: { productSlug: "plaid-shirt" }) {
    reviews {
      data {
        id
        name
        product
        comment
        rating
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "product": {
      "reviews": {
        "data": [
          {
            "id": 3,
            "name": "Oregon Person",
            "product": "plaid-shirt",
            "comment": "After wearing this shirt for 2 days, I realized it was made of cotton. I am allergic to cotton.",
            "rating": 1.5
          },
          {
            "id": 6,
            "name": "Another Person",
            "product": "plaid-shirt",
            "comment": "This shirt is okay. It lost a button, but I sewed it back on.",
            "rating": 3.5
          },
          {
            "id": 7,
            "name": "Third Person",
            "product": "plaid-shirt",
            "comment": "I love this shirt. I wear it all the time.",
            "rating": 4.5
          }
        ]
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Remote Fields 3

**Try this yourself:** Query the `reviews` remote field inside the **Product** model for the `blue-running-shoes` entry. Return the `rating` and `comment` for each review.

<Tabs panelHeight={220}>
  <TabsItem label="Solution">

```graphql
query MyQuery {
  product(where: { productSlug: "blue-running-shoes" }) {
    reviews {
      data {
        rating
        comment
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Top-level Remote Fields 1

This query fetches landing page data and review data in a single API call. The `landingPage` and `reviews` fields are at the same level in the query because `reviews` is a top-level remote field on the Query model. It is not nested inside any content model.

<Tabs panelHeight={420}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  landingPage(where: { link: "/" }) {
    landingPageTitle
    link
    sellerInformation {
      businessName
      slug
      businessDescription {
        text
      }
    }
  }
  reviews(productSlug: "black-leather-shoes") {
    data {
      id
      name
      product
      comment
      rating
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "landingPage": {
      "landingPageTitle": "Home",
      "link": "/",
      "sellerInformation": {
        "businessName": "My business",
        "slug": "my-business",
        "businessDescription": {
          "text": "This is a description of my business"
        }
      }
    },
    "reviews": {
      "data": [
        {
          "id": 1,
          "name": "First Person",
          "product": "black-leather-shoes",
          "comment": "These shoes are both the most comfortable and the most stylish I have ever owned.",
          "rating": 4.5
        },
        {
          "id": 4,
          "name": "Second Person",
          "product": "black-leather-shoes",
          "comment": "These would be better if they were red.",
          "rating": 2.5
        },
        {
          "id": 5,
          "name": "Third Person",
          "product": "black-leather-shoes",
          "comment": "I've worn these for 3 years and they are still in great shape.",
          "rating": 4.5
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

A single API call returned both Hygraph content and external review data with no middleware. This is Content Federation working as configured in lessons 5.1 through 5.3.

## Top-level Remote Fields 2

**Try this yourself:** Query the `reviews` top-level remote field for `productSlug: "plaid-shirt"`. Return only the `product` and `rating` fields.

<Tabs panelHeight={200}>
  <TabsItem label="Solution">

```graphql
query MyQuery {
  reviews(productSlug: "plaid-shirt") {
    data {
      product
      rating
    }
  }
}
```

  </TabsItem>
</Tabs>

## What's next

<Button
  href="/docs/getting-started/tutorial/tutorial-write-mutations"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Lesson 7.2 - Write mutations</Button>

Or, go to the [Tutorial overview](/docs/getting-started/tutorial/tutorial-overview) for the full lesson list.


---
# Manage billing and plans

Source: https://hygraph.com/docs/getting-started/update-billing

**Project Owners** can manage project billing and plans by going to **Project Settings > General > Billing**.

## Manage billing

![Billing details](/images/docs/user-guides/update-billing.png)

This screen displays information about your current plan, usage, and billing details.

To view billing details related to your account, click **Billing details** in the top-right corner of the screen:

![Account - Billing details](/images/docs/user-guides/billing-details-account.png)

The account billing details screen includes information about your subscription, invoices, account balance, and stored billing information.

## Manage plan

To manage your plan, click **Manage plan** at the top-right of the screen. This view shows a side-by-side comparison of all available plans.

![Manage plan](/images/docs/user-guides/billing-manage-plan.png)

You can compare plans on a yearly or monthly basis, and manage your upgrade directly from here. If you see that some plans are disabled for selection, this is because your project goes over the limits defined by those plans.

![Disabled plans in the Manage plan screen](/images/docs/user-guides/billing-over-limits.png)

## Commercial limits

<Alert theme="info">

The limits for **API calls** and **Content entries** are not updated in real time. These values are refreshed once daily by a scheduled job. Any actions that affect these limits are reflected the following day after the job has run.

The **API calls** and **Asset traffic** limits are aggregated across all environments within a project. All other limits are not shared between environments and apply only to the `master` environment.

</Alert>

### Hobby plan

| PROJECT CAPABILITIES              | LIMITS  |
| --------------------------------- | ------- |
| Content entries                      | 1000    |
| API calls                    | 500,000 |
| AI tokens                    | 100,000 |
| Asset traffic (GB)               | 100     |
| Seats                             | 3       |
| Asset upload size (MB)           | 50      |
| Models                       | 20      |
| Components                   | 10      |
| Locales                      | 2       |
| Remote Sources                    | -       |
| Content stages                    | 2       |
| Version retention period          | -       |
| Environments                 | 1       |
| Webhooks                     | 5       |
| API tokens                      | 3       |

| PLATFORM CAPABILITIES                   | LIMITS |
| --------------------------------------- | ------ |
| Standard roles                          | 2      |
| Custom roles & permissions              | -      |
| Rate limits (uncached requests / RPS)   | 5      |

### Growth plan

| PROJECT CAPABILITIES              | LIMITS    |
| --------------------------------- | --------- |
| Content entries                      | 10,000    |
| API calls                    | 1,000,000 |
| AI tokens                    | 300,000 |
| Asset traffic (GB)               | 500       |
| Seats                             | 10        |
| Asset upload size (MB)           | 200       |
| Models                       | 40        |
| Components                   | 20        |
| Locales                      | 3         |
| Remote Sources                    | 1         |
| Content stages                    | 2         |
| Version retention period          | 14 days   |
| Environments                 | 2         |
| Webhooks                     | 10        |
| API tokens                      | 5         |

| PLATFORM CAPABILITIES                   | LIMITS |
| --------------------------------------- | ------ |
| Standard roles                          | 4      |
| Custom roles & permissions              | -      |
| Rate limits (uncached requests / RPS)   | 25     |

### 30-day trial

| PROJECT CAPABILITIES              | LIMITS    |
| --------------------------------- | --------- |
| Content entries                      | 40,000    |
| API calls                    | 5,000,000 |
| AI tokens                    | 100,000 |
| Asset traffic (GB)               | 2,500     |
| Seats                             | 40        |
| Asset upload size (MB)           | 1000      |
| Models                       | 150       |
| Components                   | 100       |
| Locales                      | 15        |
| Remote Sources                    | 6         |
| Content stages                    | 3         |
| Version retention period          | 30 days   |
| Environments                 | 6         |
| Webhooks                     | 25        |
| API tokens                      | 10        |

| PLATFORM CAPABILITIES                   | LIMITS |
| --------------------------------------- | ------ |
| Standard roles                          | 4      |
| Custom roles & permissions              | 5      |
| Rate limits (uncached requests / RPS)   | 50     |

### Enterprise plan

| PROJECT CAPABILITIES              | LIMITS         |
| --------------------------------- | -------------- |
| Content entries                      | 1,000,000+     |
| API calls                    | 50,000,000+    |
| AI tokens                    | 2,000,000+ |
| Asset traffic (GB)               | 25,000+        |
| Seats                             | 200            |
| Asset upload size (MB)           | Custom         |
| Models                       | up to 500      |
| Components                   | up to 150      |
| Locales                      | up to 80       |
| Remote Sources                    | up to 10       |
| Content stages                    | up to 5        |
| Version retention period          | up to 365 days |
| Environments                 | Up to 10       |
| Webhooks                     | Up to 100      |
| API tokens                      | Up to 30       |

| PLATFORM CAPABILITIES                   | LIMITS    |
| --------------------------------------- | --------- |
| Standard roles                          | 4         |
| Custom roles & permissions              | Up to 30  |
| Rate limits (uncached requests / RPS)   | Up to 500 |


---
# Content federation

Source: https://hygraph.com/docs/core-concepts/content-federation

Content federation lets you combine data from multiple systems and expose it through a single GraphQL API endpoint without migrating the content itself. Instead of moving product data from a commerce platform, inventory from a warehouse system, or reviews from a third-party service into Hygraph, you connect those sources directly and query everything from one place.

![Content Federation](/images/docs/getting-started/fundamentals/content-federation01.png)

## How content management has evolved

The relationship between content management and content delivery has changed significantly over time.

Traditional CMSs created a **one-to-one** relationship. Content was managed and presented by the same system, tightly coupled together.

The headless CMS decoupled content management from the presentation layer, enabling a **one-to-many** relationship. Content is managed in one place and served via API to websites, apps, smart TVs, and more.

Today, organizations need to go further. Content no longer lives in a single system. It is spread across legacy CMSs, PIMs, DAMs, SaaS tools, commerce platforms, and more. This creates the need for a **many-to-many** relationship, where content from multiple sources can be unified and delivered to multiple frontends. That is what content federation enables.

![What is Content Federation?](/images/docs/getting-started/fundamentals/content-federation02.png)

## What is content federation?

Content federation is the process of sourcing data from multiple systems and making it available through a single GraphQL API, without duplicating or migrating the underlying content.

In Hygraph, this is powered by **remote sources**. Remote sources allow you to connect external APIs, whether GraphQL or REST, directly to your Hygraph project. Once connected, content editors can reference data from those sources alongside native Hygraph content, and developers can fetch everything in a single API call.

The use cases below show what content federation looks like in practice.

## Use cases

### E-commerce

An e-commerce team typically manages product descriptions, editorial content, and campaign pages in Hygraph, while product pricing, stock levels, images, and categories live in a commerce platform such as Shopify, BigCommerce, or commercetools. Without content federation, keeping these in sync requires either migrating data into Hygraph or building custom middleware to stitch them together on the frontend.

With content federation, editors reference products directly from the commerce platform using a product picker or SKU. When a page is rendered, Hygraph fetches the latest pricing and inventory from the commerce system automatically. Developers make one API call and get everything back in a single response. Pricing changes, stock updates, and product launches are reflected immediately, with no manual updates required in Hygraph.

### Travel

A travel platform aggregates content from multiple providers, such as flight schedules from an airline API, hotel availability from a booking platform, and car rental options from a separate fleet management system. Managing this in a traditional CMS would require syncing data from all three sources on a schedule, which introduces lag and risks serving outdated availability or pricing to users.

With content federation, Hygraph connects directly to each provider's API. Editorial content, such as destination guides, travel tips, and curated itineraries, lives natively in Hygraph, while live availability and pricing are pulled from the provider APIs at query time. Customers see accurate, real-time information without the content team having to manage data imports or the development team having to maintain a separate aggregation layer.

### Stock and inventory management

A manufacturer or retailer operating across multiple warehouses needs to surface real-time inventory data on their website or internal tools. Stock levels change constantly and vary by location, making it impractical to maintain a copy of that data in the CMS.

With content federation, Hygraph connects to the warehouse management system or ERP and pulls live inventory data alongside product content. Editors manage product descriptions, specifications, and marketing copy in Hygraph, while stock levels, lead times, and availability by location come directly from the source system. The result is a product page that always reflects actual inventory, with no synchronization scripts and no stale data.

## Benefits

**Eliminates content silos**

Content federation sources data directly from existing systems through a single API. Teams no longer need to migrate data from legacy platforms, and the frontend always receives the most current version.

**Supports live data**

For data that changes frequently, such as pricing, inventory, availability, and weather, content federation ensures the frontend always reflects the latest state. There is no risk of stale data from manual updates or scheduled syncs.

**Preserves data integrity**

With a single source of truth per data type, content federation removes the duplication that leads to inconsistencies. Data is not copied across systems. Instead, it is referenced programmatically from its origin.

**Reuses existing content**

Content that already exists in other systems can be brought into Hygraph without transformation or re-entry. Teams choose the best tool for each job and federate the results rather than consolidating everything into one platform.

**Gives editors more autonomy**

Because data flows through Hygraph rather than being stitched together on the frontend, editors can control what gets displayed on the final pages without requiring developer involvement for every change.

**Connects third-party APIs**

Hygraph can federate content from any API, regardless of whether it is GraphQL or REST, and expose it through a unified GraphQL endpoint. This includes public databases, review platforms, travel aggregators, stock management systems, and more.

## What's next

To start using content federation, configure a remote source in your Hygraph project.

- [Remote sources](/docs/developer-guides/remote-data/remote-sources): Full configuration instructions for connecting external APIs to your project.
- <Link href="https://hygraph.com/blog/federate-remote-data-sources-into-graphql-apis#building-a-restaurant-blog-with-hygraph-and-yelp-api" target="_blank">Building a restaurant blog with Hygraph and the Yelp API</Link>: A hands-on tutorial that walks through setting up a remote source in a real project.

---
# Best practices

Source: https://hygraph.com/docs/core-concepts/content-modeling/content-modeling-best-practices

A well-designed schema is one your editors, developers, and business stakeholders can all work with confidently. These best practices cover the decisions that have the most impact on the quality and longevity of your schema.

## Plan before you build

The most common cause of schema problems is starting in the schema editor too early. Before adding a single model, you should have:

- A clear picture of your business domain and the content it produces
- A list of object domains and their attributes, agreed on as a team
- A rough domain model showing how those objects relate to each other

Building without this foundation leads to models that reflect how content is currently stored rather than how it should be structured — and restructuring later is expensive once editors have created content against the schema.

For a guided walkthrough, see [Plan your content model](/docs/core-concepts/content-modeling/plan-your-content-model).

## Model content semantically

Model what a piece of content is, not how it will look on a specific frontend.

A model named `HeroBanner` with fields like `backgroundGradient` and `ctaButtonColor` is tightly coupled to a single frontend layout. A model named `FeaturedArticle` with fields like `headline`, `summary`, and `coverImage` describes content. The second approach works across any website, mobile app, or third-party integration, without requiring schema changes.

This matters most if you plan to deliver content to more than one channel. Even if you are starting with a single channel, semantic models are easier to extend and maintain over time.

## Keep models focused

Each model should represent one clear concept. If you find yourself adding a field that does not belong to the core concept a model represents, that is a signal to either create a new model or use a component.

Models that try to serve too many purposes create confusion for editors, produce bloated API responses, and make the schema harder to reason about. A `LandingPage` model with 40 fields is almost always a sign that several concepts have been collapsed into one.

## Use components for repeated field groups

If the same group of fields appears on more than one model, make it a component. Examples include:

- SEO metadata (`metaTitle`, `metaDescription`, `canonicalUrl`)
- Address fields (`street`, `city`, `country`, `postalCode`)
- Call-to-action blocks (`headline`, `bodyText`, `buttonLabel`, `buttonUrl`)

Defining these once as components means you update them in one place. If you later need to add an `ogImage` field to your SEO component, it propagates to every model that uses it automatically.

Use modular components when editors need to compose content from a variable set of building blocks. For example, a page that can contain any combination of hero sections, feature grids, and testimonials.

## Define relationships explicitly

Avoid duplicating data across models. If two models share a concept, use a reference field rather than adding author fields to both models. For example, both a `Product` and a `BlogPost` refer to an `Author`.

Explicit relationships have several benefits:
- Modifying an author's name or photo updates it wherever the author is referenced
- You can query related content in a single API call
- The schema accurately reflects how your business domain is structured

When setting up a two-way reference, think carefully about whether the relationship is one-to-one, one-to-many, or many-to-many, before creating the field.

## Establish naming conventions early

Inconsistent naming creates confusion for editors and makes the API harder to work with. Agree on a naming convention before building and apply it consistently. A few patterns worth deciding on upfront:

- **Field naming**: Stick to camelCase, which is the Hygraph default for API IDs.
- **Boolean fields**: Prefix with `is` or `has` to make the meaning clear (`isPublished`, `hasFeaturedImage`).
- **Reference fields**: Name them after the model they point to, in singular or plural depending on cardinality (`author` for one, `authors` for many).
- **Model names**: Use singular nouns (`Article`, not `Articles`).

Naming conventions are especially important in larger projects where multiple developers and editors work on the schema over time.

## Design for editorial usability

A schema that is technically correct but difficult to use will slow down content creation and lead to errors. When adding fields to a model, consider:

- **Field order**: Put the most important fields at the top of the form. Editors fill forms top to bottom.
- **Required fields**: Only mark a field as required if an entry genuinely cannot be published without it. Over-requiring fields creates friction.
- **Field descriptions**: Use the description option on fields to explain what is expected, especially for fields where the purpose is not obvious from the name.
- **Enumerations over free text**: Where a field has a fixed set of valid values, use an enumeration rather than a text field. This prevents inconsistent data entry and reduces editorial errors.

## Plan for growth

A schema that works for your current content volume may not work at scale. A few things to consider:

- **Avoid deeply nested structures**: Deep nesting creates complex queries and can affect API performance. If you find yourself nesting components inside components inside components, reconsider the structure.
- **Use environments to test schema changes**: Before making structural changes to a live schema, test them in a separate environment to verify the impact on queries and editorial workflow.
- **Revisit the schema periodically**: As the business changes, the schema should change with it. A periodic review against current business goals catches misalignment before it becomes a problem.

## Dos and don'ts

Use this as a quick-reference checklist when reviewing a schema.

### Dos

| Guideline                               | Description                                                                                                                                     |
|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| **Start with research**                 | Begin with desk research and stakeholder interviews to define business goals and user needs before opening the schema editor.                   |
| **Deconstruct the domain**              | Break your business down into key object domains and their relationships before deciding what goes into the schema.                             |
| **Work with a cross-functional team**   | Involve people from multiple departments. Efficient modeling requires editorial, technical, and strategic perspectives.                         |
| **Prioritize flexibility**              | Design a schema that can accommodate new models and structural changes as the business evolves.                                                 |
| **Keep structure separate from design** | Base your content model on relationships and meaning, not on how content will look visually on the frontend.                                    |
| **Keep it as simple as possible**       | A simpler model is easier to maintain and easier for editors to work with. Model for meaning, not for layout.                                   |
| **Define clear relationships**          | Use reference fields to connect related models rather than duplicating data. Clear relationships make content reusable and queries predictable. |
| **Use components**                      | Create reusable groups of fields with components to reduce redundancy across models.                                                            |
| **Establish taxonomy early**            | Define a classification system at the start of the project to improve content discoverability and ensure consistent categorization.             |

### Don'ts

| Don't                                           | Description                                                                                                                           |
|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| **Don't model alone**                           | Content modeling affects everyone who works with the CMS. It should always involve a cross-functional team.                           |
| **Don't overcomplicate the model**              | Unnecessary complexity slows development, makes content management harder, and can create performance problems.                       |
| **Don't overlook relationships**                | Failing to define relationships between models leads to duplicated data and missed opportunities for content reuse.                   |
| **Don't ignore scalability**                    | Make sure your schema can grow. A model that works perfectly today can become a bottleneck as the business changes.                   |
| **Don't assume editor needs**                   | Always talk to your editors. Never guess at what their workflow requires — ask them directly.                                         |
| **Don't use inconsistent taxonomy**             | Inconsistent categorization creates confusion and makes content hard to manage. Agree on terms as a team before you start.            |
| **Don't duplicate content unnecessarily**       | Duplicating content increases maintenance overhead and introduces the risk of inconsistencies. Use references and components instead. |
| **Don't isolate the model from business goals** | Align your schema with what the business is trying to achieve, and revisit that alignment periodically as goals change over time.     |

## What's next

- [Plan your content model](/docs/core-concepts/content-modeling/plan-your-content-model): A practical guide to research, stakeholder involvement, and schema design.
- [Content modeling walkthrough](/docs/core-concepts/content-modeling/content-modeling-walkthrough): See these principles applied in a complete schema walkthrough.

---
# Content modeling in Hygraph

Source: https://hygraph.com/docs/core-concepts/content-modeling/content-modeling-in-hygraph

Once you have a clear picture of your content model conceptually, you need to know how to express it in Hygraph. This page covers the schema building blocks available to you: what each one is, what it does, and when to use it.

![Content modeling with Hygraph](/images/docs/user-guides/content-modeling-with-hygraph.png)

## Models

A model is the core building block of your schema. It defines the structure of a single kind of entry. `Article`, `Author`, `Product`, and `Category` are all examples of models.

In Hygraph, every model you create automatically generates the corresponding GraphQL queries and mutations in your Content API. You do not write any API code manually; instead, the schema editor generates it as you build.

Think of a model as analogous to a database table. The model defines the structure and individual content entries are the rows.

## Fields

Fields define what data a model stores. Each field has a type that determines both the kind of data it accepts and how it appears in the content editor. A `Single line text` field renders as a text input; an `Asset picker` field renders as a file uploader; a `Boolean` field renders as a toggle.

Hygraph provides the following scalar field types:

| Type             | Use for                                        |
|------------------|------------------------------------------------|
| Single line text | Short strings: titles, names, slugs            |
| Multi line text  | Longer plain text without formatting           |
| Rich text        | Formatted content with headings, links, embeds |
| Markdown         | Markdown-formatted content                     |
| Integer          | Whole numbers                                  |
| Float            | Decimal numbers                                |
| Boolean          | True/false values                              |
| Date             | Date without time                              |
| Date and time    | Date with time                                 |
| Color            | Hex color values                               |
| Location         | Geo coordinates                                |
| JSON             | Arbitrary JSON data                            |

For the complete field type reference including configuration options, see [Field types](/docs/api-reference/schema/field-types).

### Field modifiers

Every field supports a set of modifiers that change how it behaves:

| Modifier  | Description                                                                  |
|-----------|------------------------------------------------------------------------------|
| Required  | The field must have a value before an entry can be saved                     |
| Unique    | No two entries in the same model can share the same value for this field     |
| List      | The field stores multiple values of the same type rather than a single value |
| Localized | The field stores a separate value per locale                                 |

Modifiers can be combined. A localized, required `Single line text` field, for example, must have a value in each locale where you save that localization. When publishing, you can select which locales to include; the default locale is always required.

For the full modifier reference, see [Field configuration](/docs/api-reference/schema/field-configuration).

## References

References connect models to each other. A reference field on a `Product` model that points to a `Product Categories` model creates a relationship between the two. You can navigate from a product to its category and query both in a single API call.

Hygraph supports two-way references, which means the relationship is visible from both sides. When you create a reference from `Product` to `Product Categories`, a reverse field is automatically available on `Product Categories` that lists all products associated with that category.

References can be configured to allow one or many related entries, and they can be restricted to a single model or open to multiple model types (using a union reference).

![References](/images/docs/getting-started/content-modeling/hygraph-relations.png)

## Components

A component is a reusable group of fields. Unlike a model, a component cannot exist as a standalone entry. It is always embedded within a model or another component.

Components are useful when the same group of fields appears across multiple models. An `SEO` component containing a meta title, meta description, and canonical URL field, for example, can be added to every model that needs it. Update the component definition once and it updates everywhere.

Hygraph supports two types of component fields:

| Type              | Description                                                                                 |
|-------------------|---------------------------------------------------------------------------------------------|
| Basic component   | Embeds a single component type. Can allow one or multiple instances.                        |
| Modular component | Allows editors to choose from a set of different component types when filling in the field. |

Modular components are particularly powerful for page-building patterns, where editors can compose a page from a defined set of blocks, such as a hero, a feature list, a testimonial. No developer support is required to create a separate model for each page layout.

![Components](/images/docs/getting-started/content-modeling/composable.png)

## Enumerations

An enumeration (enum) defines a fixed set of allowed values for a field. At the API level, GraphQL enums provide schema-level validation. A field typed to an enum can only contain one of the defined values.

Enums work well for status values (`DRAFT`, `PUBLISHED`, `ARCHIVED`), sort orders (`NAME_ASC`, `PRICE_DESC`), or any other field where the set of valid values is known in advance and should be enforced.

## Taxonomies

Taxonomies let you define hierarchical, centrally managed vocabularies that classify content across multiple models. Each taxonomy is a tree of nodes arranged in a parent-child hierarchy, supporting up to six levels of depth. For example: `Root → Category → Subcategory → Topic`

Once defined, a taxonomy is applied to a model as a taxonomy field. Editors select a node from the hierarchy when creating or updating a content entry. At the API level, a taxonomy field exposes two values:

- `value`: The taxonomy node assigned to the entry.
- `path`: An array of the full hierarchy path up to the assigned node.

This path-based structure enables advanced GraphQL filtering using operators like `descendants_of`, making taxonomies well suited to faceted navigation, personalized content feeds, and search filtering.

## System artifacts

Hygraph automatically generates a set of models, fields, and capabilities that every project includes by default.

### Asset model

The `Asset` model stores uploaded files: images, videos, audio files, and PDFs. Every project has one automatically.

Hygraph includes a built-in image transformation API that lets you crop, resize, and reposition images at query time by passing transformation parameters in the URL or GraphQL query, rather than storing multiple variants.

### User model

Every Hygraph project member is a `User`. The user model is managed automatically and is connected to every content entry and asset, so you can always identify who created, updated, or published a piece of content.

User data is also available through the Content API, so you can query author names and avatars alongside content if your application needs it.

### System fields

Hygraph adds the following fields to every model automatically. You do not need to define them.

| Field              | Type     | Description                                |
|--------------------|----------|--------------------------------------------|
| `id`               | String   | A unique identifier for each entry         |
| `createdAt`        | DateTime | When the entry was first created           |
| `updatedAt`        | DateTime | When the entry was last modified           |
| `publishedAt`      | DateTime | When the entry was last published          |
| `createdBy`        | User     | The user who created the entry             |
| `updatedBy`        | User     | The user who last modified the entry       |
| `publishedBy`      | User     | The user who last published the entry      |
| `documentInStages` | [model]  | Query the current document in other stages |

## Modeling for content reuse

If you plan to deliver content across multiple platforms, such as a website, a mobile app, a third-party integration, keep your models free of presentational information.

A model named `Hero` with fields like `backgroundGradient` and `buttonAlignment` is tightly coupled to a specific frontend layout. A model named `FeaturedArticle` with fields like `headline`, `summary`, and `coverImage` describes content, not presentation. The second approach works across any platform, whereas the first only works for one.

This principle is called **semantic modeling**: model what a piece of content *is*, not how it should *look*. Hygraph's API delivers the data; the frontend decides what to do with it.

If you are building for a single channel and your editors need to work independently on page layouts, structuring models closer to your frontend component structure is a reasonable trade-off. Just be aware that it reduces content reusability.

## Access controls

Once your schema is defined, you can configure fine-grained permissions for every model and field. Permissions control what content editors can see and edit in the UI, and what API tokens can read or write through the Content API.

For example, you can create an editor role that can update `Article` entries but cannot publish them, or an API token scoped to read-only access on a subset of models.

For the full permissions reference, see [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions).

## What's next

- [Plan your content model](/docs/core-concepts/content-modeling/plan-your-content-model): A practical guide to research, domain modeling, and schema design before you start building.
- [Field types](/docs/api-reference/schema/field-types): Complete reference for all field types and their configuration options.
- [Field configuration](/docs/api-reference/schema/field-configuration): Reference for field modifiers, validations, and appearance settings.
- [Content modeling walkthrough](/docs/core-concepts/content-modeling/content-modeling-walkthrough): See all of these concepts applied in a complete schema walkthrough.

---
# Content modeling overview

Source: https://hygraph.com/docs/core-concepts/content-modeling/content-modeling-overview

Before you create a model or add a single field in Hygraph, you need a content model. It determines how your content is structured, how pieces of content relate to each other, and how your team works with it every day. A well-designed content model makes your schema easy to extend, your API predictable, and your editorial workflow efficient. A poorly designed one creates bottlenecks that no amount of tooling can fix.

This page covers the foundational questions you need to answer before opening the schema editor.

## What is content modeling?

A content model is the blueprint for your content. It defines what types of content exist in your system, what each type contains, and how types relate to each other.

In Hygraph, the content model lives in the schema editor. Each **model** represents a content type. For example, `Article`, `Author`, or `Product`. Each model contains **fields** that define the shape of an entry: a title, a publication date, a cover image, a reference to another model. The relationships between models that are defined through reference fields make a content model more than a collection of forms.

### What is structured content?

Structured content is data organized into discrete, well-defined elements rather than one undifferentiated block of text. Instead of a single document, you have a title field, a summary field, a date field, an image field. Each field has a clear purpose and is independently retrievable.

The practical consequence is reusability. A product name, price, and cover image defined once in a `Product` model can appear on a product detail page, a category listing, a homepage feature, and a search result, without any duplication. 

Content modeling is the step that formalizes this structure. Identify how the concepts in your business domain relate to each other and translate that into a schema. The schema then governs how content is created, stored, queried, and reused.

![Structured content](/images/docs/getting-started/content-modeling/hygraph-one-graphql-api.png)

## Why content modeling matters

A content model sits at the intersection of your business goals, your users' needs, your editors' workflows, and your developers' requirements. A model that ignores any one of these groups will create friction for that group.

Here is what poor content modeling looks like in practice:

- **Performance problems**: Complex queries, deeply nested structures, and redundant data slow down your application and increase API response times.
- **Duplicate content**: Without clear relationships, editors create the same content multiple times in different places. Updates become inconsistent, maintenance becomes expensive.
- **Scalability limits**: Rigid, tightly coupled structures resist change. Adding a new content type or distribution channel becomes a much larger undertaking than it should be.
- **Editor friction**: A CMS built on a poorly designed model is difficult to navigate. Forms don't match how editors think about content, and content quality drops as a result.
- **Developer friction**: An API shaped by a bad model is hard to work with. Developers spend time compensating for schema decisions rather than building features.

In these scenarios, the CMS is not the bottleneck, but the model is.

## When to start

Before you write code, configure a frontend, or create a single entry, you need to think about content modeling.

The reason is structural. Content modeling is a bottom-up process. You define the shape your data will take, how it will connect, and how it will grow. That definition then informs every decision downstream, such as API design, frontend architecture, editorial workflow, and integration strategy.

Hygraph lets you adjust your schema at any point, and [environments](/docs/api-reference/basics/environments) make it safer to test structural changes without touching production data. But the later a change is introduced, the harder it becomes. Once you have live content, schema changes can require data migrations, which cost time and resources. A solid model upfront prevents that.

<Alert theme="info">

If you are already mid-project and considering a large structural change, use [Hygraph environments](/docs/api-reference/basics/environments) to test the change in isolation before applying it to your production schema.

</Alert>

## Who should be involved

Content modeling is a cross-functional activity. No single person has full visibility into the business goals, user needs, editorial workflows, and technical constraints that a good model has to balance.

![Who should be involved](/images/docs/getting-started/content-modeling/why-content-modeling-matters.png)

- **Content creators**: The people who use the CMS every day. Their workflow determines what fields and structures need to exist. Involve them early and interview them directly rather than guessing at their needs.
- **Designers**: Whether you start with the content model, wireframes, visual designs, or code, the team designing your project should be involved in thinking through the design of your content as well.
- **Business stakeholders**: Whoever is accountable for business outcomes should weigh in on what content serves those outcomes.
- **Developers**: Developers understand technical constraints such as performance, API shape, integration requirements. Their input prevents decisions that are editorially convenient but technically expensive.
- **Content strategist**: If your team has one, this person should lead or facilitate the modeling process. They bridge the gap between business needs and content structure.

The goal is to have a model that no single group had to compromise on because all groups helped shape it.

## Where to model your content

Complete your initial research and domain modeling before opening the schema editor. Once you have a clear picture of your content types and relationships, build and iterate directly in Hygraph rather than maintaining a separate planning document that will diverge from the real schema.

Working in the schema editor means you can see exactly what an editor will see when filling in a content form, based on the fields you have defined. You can test queries against your schema in real time to verify the API shape before building against it. You can use environments to experiment with structural changes safely.

Running modeling sessions inside Hygraph with editors, developers, and stakeholders is one of the most effective ways to catch problems early and build a shared understanding of the schema before content creation begins.

## What's next

- [Content modeling in Hygraph](/docs/core-concepts/content-modeling/content-modeling-in-hygraph): Learn how Hygraph's schema primitives (models, fields, components, enumerations) work before you build.
- [Plan your content model](/docs/core-concepts/content-modeling/plan-your-content-model): A practical guide to research, stakeholder sessions, domain modeling, and schema design.
- [Best practices](/docs/core-concepts/content-modeling/content-modeling-best-practices): Best practices for designing a scalable, maintainable, and editor-friendly content model.
- [Content modeling walkthrough](/docs/core-concepts/content-modeling/content-modeling-walkthrough): A complete walkthrough of building a schema from scratch.

If you are following the Getting Started tutorial, these concepts are applied directly in [Lesson 1.1: Design your content models](/docs/getting-started/tutorial/tutorial-design-content-models).


---
# Content modeling walkthrough

Source: https://hygraph.com/docs/core-concepts/content-modeling/content-modeling-walkthrough

This walkthrough takes you through the full content modeling process using a bookshop website as an example. Starting with research and stakeholder interviews, you will build a domain model with your team and then translate it into a working Hygraph schema. Following this method produces a schema that is structured, scalable, and straightforward for both editors and developers to work with.

## Prerequisites

- Read [Content modeling overview](/docs/core-concepts/content-modeling/content-modeling-overview) for the conceptual foundation.
- Read [Content modeling in Hygraph](/docs/core-concepts/content-modeling/content-modeling-in-hygraph) to understand models, fields, components, and other schema primitives.
- Read [Plan your content model](/docs/core-concepts/content-modeling/plan-your-content-model) for guidance on the research and domain modeling process.
- Have a Hygraph project ready. If you don't have one yet, [create a project](/docs/getting-started/onboarding-overview) first.

## Step 1: Research and discovery

Content modeling starts with research, not with the schema editor.

For this example, imagine you have been asked to build a content model for a chain of bookshops. Start with **desk research** to understand how bookshop websites typically structure their content. This would include book details, genres, authors, reviews, and so on.

Once you have a basic understanding, interview key stakeholders:

- **Content creators** to understand how they enter book details, manage inventory, and create content day-to-day.
- **Sales team** to learn what information supports the purchasing decision and how customers interact with the site.
- **Developers** to understand technical requirements, preferred stack, and how content needs to be structured for performance.
- **Marketing team** to identify what drives engagement and what promotional content needs to be supported.

After your research and interviews, compile a list of **terms** that will form the foundation of your content model:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - Books
        - Authors
        - Genres
        - Reviews
      </div>
      <div className="flex-1">
        - Price
        - ISBN
        - Availability
        - Promotions
      </div>
    </div>

### Map the relationships

With your terms defined, think through how these concepts relate to each other:

- Each **Book** is written by one or more **Authors**.
- Each **Book** belongs to one or more **Genres**.
- Each **Book** may have multiple **Reviews**.
- Each **Book** has a single **ISBN**.
- Each **Genre** may be associated with multiple **Books** and **Authors**.
- Each **Book** has a **Price**.

Next, separate **object domains** (things that will become models) from **attributes** (values that describe an object). `Price`, `ISBN`, and `Availability` are attributes of `Book`, not models in their own right.

## Step 2: Build the domain model

Bring your cross-functional team together to build a **domain model**, which is a high-level picture of the entire business, its key objects, and the relationships between them.

The domain model is broader than what you will put into Hygraph. It covers the full scope of the business, including operational areas that are not directly relevant to the website.

Here is a domain model for the bookshop:

| Object domain           | Attributes                                                   |
|-------------------------|--------------------------------------------------------------|
| **Books**               | Title, ISBN, price, availability, summary, cover image       |
| **Authors**             | Name, biography, photo                                       |
| **Genres**              | Name, description                                            |
| **Reviews**             | User name, rating, review text                               |
| **Promotions**          | Discount name, description, amount, active period            |
| **Store locations**     | Shop name, address, contact details, operating hours         |
| **Employee management** | Employee name, role, shift schedule, contact information     |
| **Suppliers**           | Supplier name, contact information, order history, contracts |

Here are the key relationships:

| Objects                            | Relationship                                                                                                 |
|------------------------------------|--------------------------------------------------------------------------------------------------------------|
| `Books` and `Authors`              | A book is written by one or more authors. An author can write multiple books.                                |
| `Books` and `Genres`               | A book belongs to one or more genres. A genre can contain multiple books.                                    |
| `Books` and `Reviews`              | A book can have multiple reviews. A user can review multiple books.                                          |
| `Books` and `Promotions`           | A book can be associated with one or more active promotions. A promotion can apply to multiple books.        |
| `Books` and `Suppliers`            | A supplier provides one or more books. A book may be sourced from multiple suppliers.                        |
| `Store locations` and `Books`      | A store location stocks multiple books. A book may be available in multiple locations.                       |
| `Suppliers` and `Store locations`  | A supplier provides stock to one or more locations. A store location receives stock from multiple suppliers. |
| `Promotions` and `Store locations` | A promotion may apply to specific locations. A store location may have multiple active promotions.           |

<Alert theme="info" title="Scoping the schema">

The domain model covers the full business, but the Hygraph schema only needs the object domains that relate to content your users interact with. This includes books, authors, genres, and promotions. Store locations, employee management, and suppliers are essential for business operations but are not part of the customer-facing content model.

</Alert>

## Step 3: Build the schema

With a domain model in hand, identify which parts belong in Hygraph. In Hygraph, object domains become **models** and attributes become **fields**.

Here is the high-level schema:

- **Book** model: Title, ISBN, Price, Summary, Availability, Book cover, Genres (reference), Author (reference), Promotion (component field)
- **Author** model: Name, Biography, Photo, Books (reference), Genres (reference)
- **Genre** model: Name, Description, Books (reverse reference), Authors (reverse reference)

The sections below define each model in detail.

### Book model

The `Book` model is the primary content type on the bookshop website.

| Field          | Type                | Description                             |
|----------------|---------------------|-----------------------------------------|
| `title`        | Single line text    | The book's title                        |
| `isbn`         | Single line text    | A unique identifier for the book        |
| `price`        | Float               | The book's price                        |
| `summary`      | Rich text           | A description of the book               |
| `availability` | Boolean             | Whether the book is currently in stock  |
| `bookCover`    | Asset picker        | The book's cover image                  |
| `genres`       | Reference (two-way) | Links to one or more `Genre` entries    |
| `author`       | Reference (two-way) | Links to one or more `Author` entries   |
| `promotion`    | Basic component     | Adds a promotion component to the entry |

#### Promotion component

The promotion component is a reusable group of fields attached to the `Book` model. Because it is a component, the same definition can be reused on other models without duplicating the field setup.

| Field         | Type             | Description                            |
|---------------|------------------|----------------------------------------|
| `name`        | Single line text | The promotion's name                   |
| `discount`    | Enumeration      | A predefined list of discount values   |
| `description` | Rich text        | A description of the promotion         |
| `image`       | Asset picker     | An image associated with the promotion |

<Alert theme="info" title="Pro Tip">

A component is a predefined group of fields that can be reused across models without duplicating field definitions. Using a component here means promotion data is consistent wherever it appears, and changes to the component propagate automatically.

For this simplified example, promotions are embedded per book rather than modeled as shared `Promotion` entries. In a production schema where the same promotion applies to many books, use a `Promotion` model with a two-way many-to-many reference to `Book` instead.

</Alert>

### Author model

The `Author` model stores information about book authors.

| Field       | Type                | Description                          |
|-------------|---------------------|--------------------------------------|
| `name`      | Single line text    | The author's full name               |
| `biography` | Rich text           | A biographical description           |
| `photo`     | Asset picker        | A profile image                      |
| `books`     | Reference (two-way) | Links to one or more `Book` entries  |
| `genres`    | Reference (two-way) | Links to one or more `Genre` entries |

### Genre model

The `Genre` model stores genre definitions and connects to both books and authors through reference fields.

| Field         | Type                | Description                                         |
|---------------|---------------------|-----------------------------------------------------|
| `name`        | Single line text    | The genre name. For example, Fiction or Non-Fiction |
| `description` | Rich text           | Additional information about the genre              |
| `books`       | Reference (reverse) | Reverse field of the `genres` reference on `Book`   |
| `authors`     | Reference (reverse) | Reverse field of the `genres` reference on `Author` |

## What's next

You now have a schema that reflects a structured, scalable approach to content modeling. Editors can create entries efficiently, and developers can query the Content API with confidence because the relationships are explicit and field types are predictable.

<Alert theme="info" title="Iterating your content model">

As your project grows, revisit the schema periodically to check that it still aligns with your business goals. Use [environments](/docs/api-reference/basics/environments) to test structural changes safely before applying them to production.

</Alert>

| Resource                                                              | Description                                                                  |
|-----------------------------------------------------------------------|------------------------------------------------------------------------------|
| [Getting Started tutorial](/docs/getting-started/onboarding-overview) | Build a project from scratch, from schema design to frontend implementation. |
| [Hygraph recipes](/docs/recipes)                                      | Explore common schema patterns and field configurations.                     |
| [Implementation guides](/docs/implementations)                        | Step-by-step guides for connecting your Hygraph project to a frontend.       |
| [Integration guides](/docs/integrations)                              | Find out how third-party apps integrate with Hygraph to extend your project. |

---
# Plan your content model

Source: https://hygraph.com/docs/core-concepts/content-modeling/plan-your-content-model

A well-designed schema starts well before you open the schema editor. The decisions you make during planning, such as understanding your domain, aligning your team, and mapping relationships between concepts, determine whether your schema will serve you for years or constrain you within months. This guide walks through each stage of the process.

## Deconstruct your domain

Start by understanding the subject area your content will cover. Identify the key concepts in your domain and consider how they connect to each other.

Your research can begin online, but it should include conversations with subject matter experts (SMEs) and real users. The output of this process is a list of terms and definitions that you will use when building your schema. These concepts need to be clear and agreed upon before modeling begins. Ambiguous terminology leads to ambiguous models.

![References](/images/docs/getting-started/content-modeling/hygraph-references.png)

As you build your list, distinguish between **object domains** and **attributes**:

- An **object domain** is a thing that exists independently. For example, `Author` or `Book`. It will likely become a model in your schema.
- An **attribute** is a characteristic of an object. For example, `name` is an attribute of `Author`, not an object in its own right. If a concept can be answered with a specific value, it is probably an attribute. It will likely become a field in your model.

## Involve your stakeholders

Content modeling requires cross-functional input. Research gives you a starting point, but the perspectives of people across your organization, such as editors, developers, researchers, and business leaders, are what make a model genuinely usable by everyone who works with it.

### Who to involve

- **UX researchers and BI professionals**: UX researchers have detailed knowledge of user behavior and needs. BI professionals can identify business performance trends the model should support. Both help align the schema with real-world usage.
- **Individual contributors**: The people who work inside the CMS every day know what works and what doesn't. Editors know the pain points of content creation. Developers know the technical constraints. Sales and support teams know what customers actually need from the product.
- **External experts**: Depending on your subject domain, an outside expert can fill gaps that internal teams cannot cover.

### Why it matters

Collaborating across roles reduces silos, surfaces blind spots, and produces a model that serves everyone who works with it. The people who will use the schema every day should help design it.

### How to run discovery sessions

Prepare before each session. Write out your questions in advance and decide how you will capture the information. Recording sessions, with the interviewee's consent, is more reliable than notes alone.

One effective technique is **card sorting**. Write key concepts on cards and ask the interviewee to organize them into categories while explaining their reasoning. Bring blank cards so interviewees can add concepts you have not thought of yet.

After your sessions, compile what you gathered into three things:

1. A list of terms and their definitions.
2. A map of how those terms relate to each other.
3. A clear separation of object domains from attributes.

You will use all three directly when building your domain model.

## Build a domain model

Bring your cross-functional team together to build a **domain model**, which is a high-level map of your business, its key objects, and how those objects relate to each other.

The domain model covers the full scope of the business, not just what will be published through the CMS. For a bookshop, that includes inventory, orders, promotions, staff management, and suppliers, not just books and authors. You need this full picture before deciding what belongs in the schema.

A practical way to run this session is with sticky notes or a shared whiteboard tool. Arrange your object domains spatially and draw connections between them. Since you have done your research beforehand, bring a first-draft sketch rather than starting from a blank canvas. This gives the team something to react to and refine rather than building from scratch.

The result should be a shared, agreed-upon picture of how your business operates. This becomes the reference for the next step, where you decide which parts of the domain model belong in your Hygraph schema.

## Build your schema

<Alert theme="info">

You can use Hygraph's schema editor to draft and iterate on your schema as you go. This lets you see what a content entry form will look like for editors at every step of the way.

</Alert>

Your schema is the portion of the domain model you bring into Hygraph.You need to bring in only those objects that represent content your editors will create and your users will interact with. Not every object from the domain model belongs in the schema.

Look at your domain model and select the object domains relevant to published content. These become **models** in Hygraph. The attributes of each object become **fields** on those models. Relationships between objects become **reference fields**.

For example, if you have an `Author` model, then `name`, `bio`, and `picture` would be fields on it. A relationship between `Author` and `Book` would be a two-way reference field, meaning you can navigate from a book to its author and from an author to their books.

![Hygraph project schema](/images/docs/getting-started/content-modeling/hygraph-schema.png)

The result is a schema containing a set of models connected by references, where each model contains the fields that represent its attributes.

### Content templates and dynamic page composition

![Content templates & dynamic page composition](/images/docs/getting-started/content-modeling/hygraph-relations-attributes.png)

Think of each model as a template. When you defined your models and fields during planning, you were deciding what those templates would contain. Now you build them out.

Hygraph's **components** are particularly useful here. A component is a predefined group of fields that can be reused across different models without duplicating field definitions.

Component fields can be:

- **Basic**: Embeds a single component type, allowing one or multiple instances.
- **Modular**: Allows editors to choose from a set of different component types when filling in the field.

Using a modular component field, you can create a model that behaves differently depending on what the editor selects. A `Book` model could have a modular component field for banners, where editors choose between a promotional banner and a new arrivals slider, or add no banner at all. A single model can have multiple possible content configurations.

### Classification using references

A common pattern for organizing and categorizing content in Hygraph is to create a dedicated model for each category type, create entries for each category value, and connect that model to the models that need categorizing using a two-way reference field.

For example, a `Genre` model with a `name` field and a `description` field can be connected to a `Book` model via a two-way reference. Editors assign one or more genres to each book entry. At the API level, you can query all books in a given genre, or query a book and retrieve its genres in the same request — because the relationship is defined in the schema.

This approach works well when category entries need their own rich content, such as descriptions, images, or related metadata. The same `Genre` model can be referenced by multiple other models, keeping classifications consistent without duplication.

<Alert theme="info">

If you need a hierarchical, centrally governed classification system that is shared across many models, consider using Hygraph's dedicated [Taxonomies](/docs/developer-guides/schema/taxonomies) feature instead. Taxonomies are an enterprise feature and support up to six levels of hierarchy with advanced API filtering capabilities.

</Alert>

## Terminology reference

Content modeling literature uses different terminology than Hygraph. This table maps the common terms to their Hygraph equivalents.

| Content modeling term | Hygraph term          |
|-----------------------|-----------------------|
| Content model         | Schema                |
| Object domain         | Model                 |
| Content type          | Model                 |
| Attribute             | Field                 |
| Property              | Field                 |
| Relationships         | References, relations |
| Content instance      | Entry                 |

## What's next

- [Content modeling in Hygraph](/docs/core-concepts/content-modeling/content-modeling-in-hygraph): Reference for all schema building blocks, such as models, fields, components, enumerations, and system artifacts.
- [Best practices](/docs/core-concepts/content-modeling/content-modeling-best-practices): Best practices for designing a scalable, maintainable, and editor-friendly content model.
- [Content modeling walkthrough](/docs/core-concepts/content-modeling/content-modeling-walkthrough): A complete walkthrough of building a schema from scratch.

---
# Glossary

Source: https://hygraph.com/docs/core-concepts/glossary

## Basic concepts

| Concept          | Description                                                                                                                                                                                                                                                                                                                     |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| API Playground   | The [API Playground](/docs/api-reference/basics/api-playground), located on the left sidebar of the Hygraph app, allows you to experiment with querying and mutating data.                                                                                                                                                      |
| Assets           | The [Asset](/docs/api-reference/assets/assets-overview) model is included in every project by default. It is commonly used for images, but can also support any file type. Assets can be fetched, referenced, transformed, uploaded, updated, published, localized, deleted, and embedded.                                      |
| Component        | A [component](/docs/developer-guides/schema/components) is a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template where you define the fields once, and then fill them with different content every time you use it in a content entry. |
| Content modeling | The [content model](/docs/core-concepts/content-modeling/content-modeling-in-hygraph) defines the schema of your content. It describes what kind of content you want to store, how it relates to other content, and how it can be edited within Hygraph.                                                                        |
| Content views    | Hygraph features default and custom [content views](/docs/developer-guides/content/content-views). Default content views list all content entries created based on the respective models. Custom content views are filtered for specific content entries.                                                                       |
| Enumeration      | An [enumeration](/docs/api-reference/schema/enumerations) (or enum for short) can be used to group values within a type. Enums are useful for filtering and defining certain content entries in your project.                                                                                                                   |
| Model            | Models define the structure of your content. You build your schema by creating models and adding fields to them. Learn more in the [quickstart guide](/docs/getting-started/quickstart#create-a-model).                                                                                                            |
| Mutations        | Operations that allow you to insert new data or modify existing data on the server side. See [mutations](/docs/api-reference/content-api/mutations) for the full reference.                                                                                                                                                     |
| Preview URLs     | [Preview URLs](/docs/developer-guides/schema/live-preview#define-a-preview-url-template) are automatically generated links that allow you to preview content in your frontend before it is published. Configuring this feature adds a button to the content editor's right sidebar so editors can quickly access content previews.                            |
| Relations        | References, often referred to as [relations](/docs/api-reference/schema/field-types#reference), allow you to connect one or more models together, and even reference multiple models as a single field type using GraphQL Union Types.                                                                                          |
| Remote sources   | [Remote sources](/docs/developer-guides/remote-data/remote-sources) are Hygraph's content federation feature. They allow you to add content from other systems and sources to the Hygraph API without migrating the content itself.                                                                                               |
| Schema editor    | The schema editor is where you add fields, create relationships between models, and define the structure of your content. See the [Studio walkthrough](/docs/getting-started/studio-walkthrough) to learn more.                                                                                                              |
| System fields    | All default and custom models come with managed [system fields](/docs/api-reference/schema/system-fields). These fields reflect certain states of your content, such as when it was last updated or published.                                                                                                                  |
| Taxonomy         | A [taxonomy](/docs/developer-guides/schema/taxonomies) is a group of terms arranged in a hierarchical structure. Taxonomies are used to classify and logically connect content across multiple models. They are defined in the schema editor and support up to six levels of depth. Taxonomies are an enterprise feature.       |

## Content stages

This list offers a brief description of the two content stages every Hygraph project has by default.

| Stage name | Description                                                                                                                                                                                     |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Draft      | The working stage for content. Unpublished entries exist only here. Published entries also have a `DRAFT` copy for edits before re-publishing. Saving without publishing does not affect the live published version.                                                                       |
| Published  | Published content. If the published button displays green, the content has been pushed live. If it displays blue, a new draft version has been saved and the published content is now outdated. |

You can also create custom content stages for your project. See [content stages](/docs/developer-guides/content/content-stages) to find out more.

## Fields

| Field type        | Description                                                                                                                                       |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| Single line text  | [String](/docs/api-reference/schema/field-types#string) type field widget. Used for adding headings and titles.                                   |
| Multi line text   | [String](/docs/api-reference/schema/field-types#string) type field widget. Used for adding longer text such as descriptions.                      |
| Markdown          | [String](/docs/api-reference/schema/field-types#string) type field widget. A markdown editor.                                                     |
| Slug              | [String](/docs/api-reference/schema/field-types#string) type field widget. Used for adding URL-friendly identifiers to your content.              |
| Rich text         | [Text](/docs/api-reference/schema/field-types#rich-text) type field widget. A text editor with formatting.                                        |
| Number            | [Integer](/docs/api-reference/schema/field-types#integer) type field widget. Used for adding numeric fields such as IDs or identifiers.           |
| Float             | [Float](/docs/api-reference/schema/field-types#float) type field widget. Used for numbers that include decimal values, such as ratings or prices. |
| Boolean           | [Boolean](/docs/api-reference/schema/field-types#boolean) type field widget. A toggle that represents true/false.                                 |
| Date              | [Date](/docs/api-reference/schema/field-types#date) type field widget. A calendar date picker.                                                    |
| Date and time     | [Date and time](/docs/api-reference/schema/field-types#date-and-time) type field widget. A calendar date picker that includes time.               |
| JSON editor       | [JSON](/docs/api-reference/schema/field-types#json) type field widget. Allows adding arbitrary JSON structures.                                   |
| Cloudinary asset  | [JSON](/docs/api-reference/schema/field-types#json) type field widget. Allows picking assets from Cloudinary.                                     |
| Asset picker      | [Asset](/docs/api-reference/schema/field-types#asset) type field widget. Allows selecting assets from your project and supports any file type.    |
| Color             | [Color](/docs/api-reference/schema/field-types#color) type field widget. Supports HEX and RGBA.                                                   |
| Map               | [Location](/docs/api-reference/schema/field-types#location) type field widget. Allows adding geo coordinates to your content.                     |
| Dropdown          | [Enumeration](/docs/api-reference/schema/field-types#enumerations) type field widget. Allows adding a dropdown list of values to your content.    |
| Basic component   | Component type field widget. Used for a single fixed component type and can be configured for one or multiple instances. See [components](/docs/developer-guides/schema/components) to learn more.       |
| Modular component | Modular component type field widget. Used for multiple component types. See [components](/docs/developer-guides/schema/components) to learn more. |
| Reference         | [Relation](/docs/api-reference/schema/field-types#reference) type field widget. Used for content relationships.                                   |
| REST              | [REST](/docs/api-reference/schema/field-types#rest-remote-field) type field widget. Used to add external data via REST.                           |
| GraphQL           | [GraphQL](/docs/api-reference/schema/field-types#graphql-remote-field) type field widget. Used to add external data via GraphQL.                  |

## Sidebar widgets

| Widget name       | Description                                                                                                |
|-------------------|------------------------------------------------------------------------------------------------------------|
| Entry information | System sidebar widget, added to your model by default. Offers basic entry information.                     |
| Localizations     | System sidebar widget, added to your model by default. Allows viewing localized fields.                    |
| Preview           | System sidebar widget. Allows previewing content changes by adding a preview link to your content.         |
| Releases          | System sidebar widget. Allows grouping entries into content releases for coordinated publishing. Scheduled publishing is configured via publish actions and is an Enterprise feature.    |
| Stages            | System sidebar widget, added to your model by default. Allows viewing in-app content stages.               |
| Versions          | System sidebar widget, added to your model by default. Allows viewing the version history of your content. |

See [system fields](/docs/api-reference/schema/system-fields) to learn more.

## Components

| Concept            | Description                                                                                                                                                        |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Component          | A component is a predefined set of fields that can be reused across models and content entries.                                                                    |
| Component field    | A special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. |
| Component instance | A specific occurrence of a component type, containing content, inside a content entry.                                                                             |
| Nested components  | Functionality that allows you to create components within a component.                                                                                             |

See [components](/docs/developer-guides/schema/components) to learn more.

## Variants

| Concept    | Description                                                                                                                                                                                                                                                                                                          |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Base entry | The main content entry that variants are built from. Updating a variant-enabled field in the base entry does not update the same field in its variants, and vice versa.                                                                                                                                              |
| Segment    | A named reference used to target a group of users based on shared characteristics or behaviors. Segments are managed externally and referenced in Hygraph to determine which variant of a content entry is delivered to a given audience.                                                                            |
| Variant    | A personalized version of a content entry tailored to a specific audience segment. Variants inherit the structure of the main entry but allow certain fields to be customized independently, enabling content teams to deliver targeted experiences without duplicating entries. Variants are an enterprise feature. |

See [variants](/docs/developer-guides/schema/variants) to learn more.


---
# Add asset entry

Source: https://hygraph.com/docs/developer-guides/assets/add-asset-entry

![Assets - Add Entry](/images/docs/user-guides/assets-add-entry.png)

To add an asset entry, navigate to the **Assets** tab of your project and click on the `+ Add entry` button, located at the top right corner of your screen.

Unlike our [regular asset upload](/docs/developer-guides/assets/upload-asset), when you add an asset entry you can add metadata to your asset.

`Asset` is a system model that appears by default in every Hygraph project. You can edit the asset model to include the data you wish to have in your asset entries. This asset model configured in your project's schema will determine the data you can add to an asset entry.

![Assets - Add Entry](/images/docs/user-guides/assets-add-entry-screen.png)

Besides the metadata, the `+ Add entry` screen has an `Upload` button that displays the same options as our [regular asset upload](/docs/developer-guides/assets/upload-asset).


---
# Upload asset

Source: https://hygraph.com/docs/developer-guides/assets/upload-asset

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on uploading Assets](/docs/api-reference/assets/uploading-assets)

</Alert>

![Upload asset](/images/docs/user-guides/asset-upload.png)

To upload an asset, navigate to the **Assets** tab of your project and click on the `Upload` button, located at the top right corner of your screen.

A screen will pop up, prompting you to select an asset source:

![Upload asset](/images/docs/user-guides/asset-upload-screen.png)

For now, the system allows you to drop files on the screen, or browse them from your computer.

You can add assets from one or more of these sources.

As you select multiple assets, the pop up screen will display them as thumbnails.

![Upload asset](/images/docs/user-guides/asset-upload-thumbnails.png)

You will have the option to add more, or upload the ones you've already selected.

---
# Work with assets

Source: https://hygraph.com/docs/developer-guides/assets/work-with-assets

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on Assets](/docs/api-reference/assets/assets-overview)

</Alert>

## Overview

The assets manager contains all documents (images, videos, etc.) that have been uploaded to a project.

On this screen, you can sort and filter assets, configure the columns and save views just like in the **Content editor**, perform single or bulk actions, schedule asset entry releases, and upload assets.

Let's look into these in more detail.

## Switch views

You can choose whether you want your assets to display in a grid or table view.

You can find the switch at the top of the screen:

![Switch asset views](/images/docs/user-guides/assets/asset-table-views-switch.png)

### Table view

This is what the table view looks like:

![Assets - Table view](/images/docs/user-guides/assets/asset-list-view.png)

Users can open the asset entry by clicking on a table item, or use the checkboxes to perform single or bulk actions.

### Grid view

This is what the grid view looks like:

![Assets - Grid view](/images/docs/user-guides/assets/asset-table-grid-view.png)

- **Open an entry:** Open an asset entry by clicking anywhere on the thumbnail or the title.
- **Preview asset:** Click on the eye icon on an asset card to open a large asset preview. This icon appears on hover.
- **Asset selection:** Select boxes appear on hover. Selecting an asset activates selection mode. As a result:
    - A deselect all button appears at the top of the grid.
    - All checkboxes become visible on all assets.
    - Clicking on asset cards will not open the asset in selection mode.

## Sort asset entries

![Sort asset entries](/images/docs/user-guides/assets/asset-table-grid-view-sort.png)

Click on the `Sort by` dropdown menu at the top-left of the table to select a sorting option.

## Filter asset entries

![Filter asset entries](/images/docs/user-guides/assets/asset-table-grid-view-filters.png)

Click `Filter` at the top of the assets table to display the filters menu.

You can find detailed information on how to work with filters [here](/docs/developer-guides/content/using-filters).

## Bulk actions

If you select asset cards using the checkboxes, the bulk actions will display at the bottom of the table.

![Bulk actions](/images/docs/user-guides/assets/asset-table-grid-view-select-all.png)

The actions panel contains the following:

- `Show selected`: Clicking on this option displays only the selected asset entries on the list.
- `Publish`: This option starts the publishing process. Clicking on `Publish` prompts a pop up screen where you can use checkboxes to select whether non localizable fields and/or the default localization fields will be published, before clicking on the `Publish` button to finish the process. You can publish entries in batch by selecting multiple entries then clicking on `Publish`, but please consider that when using batch-publishing, non-localized fields and the default localization will always be published.
- `Unpublish`: Clicking on `Unpublish` unpublishes the selected entries.
- `Delete`: Clicking on `Delete` results in the elimination of the selected entries. Please consider that this change is permanent and cannot be rolled back.
- `Schedule`: Clicking on `Schedule` prompts a pop up screen where you can schedule publication by selecting one of the following options:
  - `Schedule entry only`: This option schedules an entry individually. After selecting this option, you'll select an `Action` (publish, or unpublish), a date and time, and a time zone. You can also use checkboxes to select which additional locales are published/unpublished - non-localized fields and the default localization will always be published.
  - `Add to an existing release`: This option allows you to select from existing releases that need to have been previously configured in your content editor. If you have configured releases, then you will be able to select one from a dropdown menu after selecting this option. Otherwise, the following message displays: **No releases available, please add one**.
  - `Add to a new release`: This option allows you to create a new release and add the current entry to it. After selecting this option and giving your new release a `Name` and `Description`, you'll select an `Action` (publish, or unpublish), a date and time, and a time zone. You can also use checkboxes to select which additional locales are published/unpublished.

<Alert theme="info" title="Pro Tip">

- **To select all asset cards**, select the `Select all` checkbox at the top of the table.
- **To clear selection**, simply deselect the `Select all` checkbox at the top of the table.
- The actions panel will also display if you select a single entry, but bear in mind that the actions will only impact the selected entry.

</Alert>

## Edit asset entries

To edit the details of an asset entry click on the asset card if you're seeing the grid view, or on an asset list item if you're seeing the table view.

![Edit asset entries](/images/docs/user-guides/assets/edit-asset-entry.png)

The edit view of asset entries allows you to edit the asset itself as well as its metadata.

To edit the metadata attached to an asset, simply edit the fields as you would do in the **Content editor**.

You will find three buttons on top of the asset image:

- `Replace`: This option replaces the asset keeping the metadata attached to it.
- `Download`: This option downloads the asset to your computer.
- `Copy URL`: This option copies the asset URL.

<Alert theme="warning">

While you can change the document attached to an asset entry by clicking `Replace` in the edit view, please note that this will change the asset URL. Make sure to replace that URL if you're using it outside of the project.

The entry `ID` will remain the same.

</Alert>

## Configure columns

![Configure columns](/images/docs/user-guides/assets/assets-configure-columns.png)

You can use the cog icon at the top-right of the assets table to configure the visible columns. Clicking on it opens a dropdown where you can select or deselect columns using the eye icons. An open eye indicates that the is visible, while a closed eye means it is hidden.

[Here](/docs/developer-guides/content/configuring-columns) you can find detailed information on how to configure columns.



---
# Accessing created content

Source: https://hygraph.com/docs/developer-guides/content/access-created-content

To access already created content, click on the Content editor tab:

![Hygraph Content Editor](/images/docs/user-guides/hygraph-content-editor.png)

Hygraph offers users a variety of ways to keep their content organized and accessible. Everyone has different preferences on how content should appear and how clean the UI should be. There are some simple settings that allow users to customize the look and feel of their content views.

Here you will find some information on how to use [filters](/docs/developer-guides/content/using-filters), how to [configure columns](/docs/developer-guides/content/using-filters), and how to [customize your content views](/docs/developer-guides/content/content-views).


---
# Configuring columns

Source: https://hygraph.com/docs/developer-guides/content/configuring-columns

Configuring columns will help you declutter your content views by hiding information that is not relevant to you.

Click on the cog icon to display the options inside, and then select which columns you would like to show in your content table by clicking on the eye icon. An open eye means the column is shown, and a closed eye means it's hidden.

You can also rearrange the position of the columns on the table by clicking on the six-dots handle next to each option and dragging them into the order you want.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xaqjjavz07w50zvdfqnp" caption="Configuring columns" />

---
# Content localization

Source: https://hygraph.com/docs/developer-guides/content/content-localization

## Overview

Localization is supported as a core feature in Hygraph. It allows a single piece of content to hold many configured locales.

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on localization](/docs/api-reference/content-api/localization)

</Alert>

## What you can do

In your project settings you can define how many locales you want to support, choosing from a range of common defaults to providing custom locales as well.

Depending on the content model and the number of locales activated in the project several locales can be available.

![Localized content fields](/images/docs/user-guides/localized-content-fields.png)

<Alert theme="info" title="Pro Tip">
Locales function by creating localized fields on the document model, not creating a duplication of the content.

You can stage, eventually version and evolve localized content entries with "per field" granularity.
</Alert>

## Adding a translation

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xasnjaw707w5b21vjr80" caption="Content Localizations List" />

1. Navigate to the Content Editor and select a view.
2. Create a new entry or, alternatively, edit an existing one.
3. Find `Localizations` on the right sidebar and click the `+` icon to add a locale variant to all fields in the content entry that support localization.

## Show or hide translated fields

You can toggle the "eye" icon on the left of a locale on the contextual sidebar of a content entry to show / hide the localized fields.

![Toggle translated fields](/images/docs/user-guides/toggle-content-localization.png)

An open eye means the localized fields are visible and a close eye means they are hidden.

---
# Content stages

Source: https://hygraph.com/docs/developer-guides/content/content-stages

## Overview

Hygraph offers two system content stages (`DRAFT` & `PUBLISHED`) plus the possibility to create custom ones depending on your plan.

<Alert theme="info" title="Are you looking for our API Reference?">
[Check out our API Reference document on content stages](/docs/api-reference/content-api/content-stages)
</Alert>

This document discusses what these stages mean and how you can use them to create workflows.

<Alert theme="warning">
**Content stages are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.
</Alert>

## What you can do

- You can save content in the `DRAFT` stage while you work on it, before it's ready to be `PUBLISHED`.
- You can use content staging to [compare versions](/docs/developer-guides/content/versioning-content) of content in different stages. 
- In case of an error, you can quickly revert changes to the `DRAFT` stage from the `PUBLISHED` stage, then use [version comparison](/docs/developer-guides/content/versioning-content) to compare the two and choose which fields to revert to the `PUBLISHED` stage. 

## System content stages

Hygraph has two system content stages, `DRAFT` and `PUBLISHED`.

`DRAFT` allows people to add and edit content without affecting published content. When the content is ready to be pushed live, it is promoted to the `PUBLISHED` stage.

<Alert theme="warning" title="Please note">

- Content cannot be consumed by others unless it's published.
- Depending on your plan, you can [create custom content stages](/docs/developer-guides/content/content-stages#custom-content-stages).
- System content stages cannot be edited or deleted.

</Alert>

![System content stages](/images/docs/user-guides/system-content-stages.png)

Content in Hygraph that has been saved but has never been published exists only in the `DRAFT` stage. When promoted to the `PUBLISHED` stage, content will exist in that stage, and also in `DRAFT`.

When you update a content entry and save without publishing, that new content will be saved in `DRAFT` and the entry will show a blue `PUBLISHED` pill on the content table, indicating that it's **outdated**.

Content being **outdated** means that the version currently saved in the `DRAFT` stage contains changes that have not yet been promoted to `PUBLISHED`.

<Alert theme="info" title="Pro Tip">
- Content will always be created in the `DRAFT` stage. Any actions that are not `publish` or `unpublish` will only affect the `DRAFT` version of a content entry. If you're using the UI, that action is `Save`; and if you're using the API, it's `create` or `update`.
- A `DRAFT` pill in the content table indicates that the content has been saved but has never been published.
- A green `PUBLISHED` pill in the content table indicates that the currently published version of the content is the latest one.
- A blue `PUBLISHED` pill in the content table indicates that the `DRAFT` version is newer than the `PUBLISHED` version. This means you will need to publish this content before it can be consumed by others.
</Alert>

## Custom content stages

Depending on your plan, you may only have access to the two system content stages that we described above, or you may have the possibility to create more.

<Alert theme="info">

- <Link href="https://hygraph.com/pricing" target="_blank">Check out our pricing page for information on plans</Link>
- [Click here to learn how to configure custom stages](/docs/developer-guides/project/configure-content-stages)

</Alert>

Paid plans allow creating custom content stages, which you can use to create more sophisticated workflows.


For instance, the following diagram shows a workflow with 3 content stages: `DRAFT`, `APPROVAL` and `PUBLISHED`.

![Hygraph workflow with 3 content stages](/images/docs/user-guides/workflow-3-content-stages.png)

<Alert theme="info" title="Pro Tip">

This feature can be particularly helpful when using **Custom Roles**. For example, if a team member should only be able to create `DRAFT` content but not move it directly to the `PUBLISHED` stage, this is possible with **Custom Roles**.

Check out our [Roles & Permissions](/docs/developer-guides/project/roles-and-permissions#custom-roles) document to learn more about **Custom Roles**.

</Alert>

---
# Working with content views

Source: https://hygraph.com/docs/developer-guides/content/content-views

## Overview

Content views are basically the way our content is displayed in the content editor. They are divided into:

- **Default views:** Generated automatically. They show the default columns configuration and without any filter criteria applied.
- **Custom Views:** Generated by users. They show a specific columns configuration and filter conditions, selected and saved by the user.

## What you can do

![Content views](/images/docs/user-guides/content-views-in-editor.png)

- You can use content views to easily navigate the content in the **Content editor**
- You can create custom content views to easily access certain content
- You can create view groups to organize your custom content views

## Update default views

When making changes to the content view - by configuring columns, or adding filters - you can save this configuration as the default view for all users of the project.

To do this, click the `View` dropdown at the top-right of the screen to display the options inside, and select the `Update view` option.

![Update default view](/images/docs/user-guides/update-view-default.png)

Default views are also reflected inside of connection models when linking other content models.

## Custom views

The default content views are the system views which list all content entries that have been created based on the respective content models. Custom content views are filtered for specific content entries.

After you customize your content table using the three features mentioned above, you can save these customizations using the Content View. This can be a helpful way of organizing your content and making it easier to find.

For example, as a content editor if you are only editing Blog posts written by Annie, you can create a content view called “Annie's Blog Posts.” This will give you quicker access and let you avoid scrolling through content to find what you are looking for.

### Create a custom view

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/4x6zdeYnQnuLTB9xpz7g" caption="Create a custom view" />

1. Navigate to the Content editor and select a model.
2. Create a change to the view by either filtering the content in the search bar at the top, or showing/hiding the columns.
3. Click the `View` dropdown at the top-right of the screen to display the options inside, and select the `Save as new view` option.
4. Provide a `Name` and, optionally, `Description`.
5. Click `Add custom view` to save.

### Update a custom view

![Update custom view](/images/docs/user-guides/edit-custom-view.png)

1. Navigate to a custom view in the Content editor.
2. Next to the title of the content view, click on the context menu to display the options inside and select `Update custom view`.
3. Apply your changes and click `Update` to save.

### Delete a custom view

![Delete custom view](/images/docs/user-guides/delete-custom-view.png)

1. Navigate to a custom view in the contextual sidebar of the content tab.
2. Next to the title of the content view, click on the context menu to display the options inside and select `Delete custom view`.
3. Confirm you want to delete.

## Organizing custom views

![Reorder custom views](/images/docs/user-guides/reorder-custom-views.png)

1. Hover your mouse next to a custom view.
2. Grab the six-dot handle to the left of the label.
3. Drag and drop to change the order.

## View groups

Custom **View Groups** let you create a group of Content Views. These can be helpful when working in larger teams as you can create a Custom View Group that contains all of the content for each person. These custom View Groups let team members create their custom views and save them all in one place.

In using these features to customize your content tables, teams will be able to set up best practices, optimize their time and experience in Hygraph and focus on creating great content.

**View Groups** allow you to customize the presentation and selection of content visible to an editor. You can show or hide different columns and filter which content should be included in the group. This allows for an optimized editorial workflow, helping editors to quickly find the content that needs their attention.

![View groups](/images/docs/user-guides/view-group.png)

### Create a view group

![Create custom view group](/images/docs/user-guides/create-custom-view-group.png)

1. Navigate to the content editor.
2. Click on the folder icon next to **Content** on the contextual sidebar to add a new view group.
3. Provide the `Name`.
4. Click `Add view group` to save.

![Save custom view group](/images/docs/user-guides/save-custom-view-group.png)

### Edit a view group

![Edit a custom view group](/images/docs/user-guides/edit-custom-view-group.png)

1. Find a custom view group in the contextual sidebar.
2. Click on the context menu and select `Edit view group`.
3. Apply your changes and click `Save` to confirm.

### Delete a view group

![Delete a custom view group](/images/docs/user-guides/delete-custom-view-group.png)

1. Find a custom view group in the contextual sidebar.
2. Click on the context menu and select `Delete view group`.
3. Confirm the deletion.

## Organizing custom view groups

![Reorder custom view groups](/images/docs/user-guides/reorder-custom-view-group.png)

1. Hover your mouse next to a custom view inside a view group.
2. Grab the six-dot handle to the left of the label.
3. Drag and drop to change the order.


---
# Creating content

Source: https://hygraph.com/docs/developer-guides/content/creating-content

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on mutations](/docs/api-reference/content-api/mutations#create-entries)

</Alert>

## How to create an entry

![Creating content with required fields](/images/docs/user-guides/create-content.png)

1. Navigate to the **Content editor**.
2. Choose a content model from the collapsible content views sidebar.
3. Click `+ Add entry` at the top-right corner of the screen.
4. Fill out the information required by your content model.
5. Click `Save` or `Save & publish` according to your workflow. Clicking `Save` will save your content onto the `DRAFT` stage, while clicking `Save & publish` will save your content onto both the `DRAFT` and `PUBLISHED` stages, respectively.

![Save and Publish content](/images/docs/user-guides/save-and-publish-content.png)

<Alert theme="info">
The content model defines which fields are required and which fields are not mandatory.
</Alert>

Hygraph allows the set-up of additional [content stages](/docs/developer-guides/content/content-stages) (e.g. a `QA` and/or `ARCHIVED` stage) depending on your plan.

The following diagram shows a simplified workflow including 3 content stages - `DRAFT`, `APPROVAL` and `PUBLISHED` - as well as two roles: **Editor** & **Editor Supervisor**.

![Hygraph workflow with 2 roles](/images/docs/user-guides/workflow-3-content-stages-2-roles.png)

## Field outline

Our field outline feature helps you reduce the time it takes to create and edit content by providing you with a visual representation of form structures.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xupwjbqc07w5vatlm3uu" caption="Field outline" />

As you work on a content entry, our field outlines will help you quickly and easily locate specific fields, even within long and complex content forms.

The field outline sidebar displays to the left of your content form and, as you scroll over it, highlights on the content form will indicate the corresponding fields.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xunvhv2r07vxcsd4n97f" caption="Field outline scroll" />

Clicking on an item on the field outline sidebar will take you to that field in the content form.

To do this with a component field, you need to click on the dropdown menu to display the component and its contents, then click on one of the fields inside the component.

## Related features

### Content stages

Hygraph allows the set-up of additional [content stages](/docs/developer-guides/content/content-stages) (e.g. a `QA` and/or `ARCHIVED` stage) depending on your plan.

The following diagram shows a simplified workflow including 3 content stages - `DRAFT`, `APPROVAL` and `PUBLISHED` - as well as two roles: **Editor** & **Editor Supervisor**.

![Hygraph workflow with 2 roles](/images/docs/user-guides/workflow-3-content-stages-2-roles.png)

### Connecting related content

For content models that have [references](/docs/developer-guides/content/using-references), you can either connect an existing entry, or create and connect a new one.

References are relations between two or more content entries that you can create in Hygraph.

There are four different reference types according to reference cardinality, which determines if it will be possible to connect one or many entries to the parent entry, as well as the directions of that relation.

[Check out our documentation on references to learn more](/docs/developer-guides/content/using-references).

---
# Customize sidebar

Source: https://hygraph.com/docs/developer-guides/content/customize-sidebar

You can configure schema sidebar adding and/or removing system and custom widgets.

## Adding widgets

![Add sidebar widgets](/images/docs/user-guides/sidebar-widgets.png)

1. Navigate to the schema builder
2. Find the model you want to customize the sidebar for
3. Click on the `Sidebar` tab
4. Under **Sidebar Widgets**, click on the widget you want to add

Depending on the widget, you may need to enter additional information before saving.

## Removing widgets

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvpkjbsq07w5eytzu2g4" caption="Removing Widgets" />

1. Navigate to the schema builder
2. Find the model you want to customize the sidebar for
3. Click on the `Sidebar` tab
4. Under **Sidebar Widgets in Use**, click on the context menu and then `Remove`

## Reordering widgets

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvrhhv5107vxqzc0ti48" caption="Reordering Widgets" />

1. Navigate to the schema builder
2. Find the model you want to customize the sidebar for
3. Click on the `Sidebar` tab
4. Under **Sidebar Widgets in Use**, click & hold the drag handle to reorder the widget, then drop it to the desired position


---
# Deleting content

Source: https://hygraph.com/docs/developer-guides/content/deleting-content

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on mutations](/docs/api-reference/content-api/mutations#delete-entries)

</Alert>

## How to delete content

![Content Quick Actions](/images/docs/user-guides/content-quick-actions.png)

1. Navigate to the Content editor.
2. Select a content model
3. Find the content item you want edit in the content entries table.
4. Check the selection box at the beginning of the row.
5. Press the trash icon with the word `Delete` at the bottom of the content table.
6. Confirm the deletion.

## Remove related content

1. Open the content entry that you want to disconnect a relation from.
2. Find the reference field.
3. Click on the context menu to the right of the content entry title and select `Delete`.

![Remove related content](/images/docs/user-guides/removing-related-content.png)


---
# Duplicating content

Source: https://hygraph.com/docs/developer-guides/content/duplicating-content

## Duplicate content entries

Inside each content entry, editors have the option to duplicate content.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/URdxjYG7SsqCrln9RS66" caption="Duplicate a content entry" />

Follow these steps to duplicate content:

1. Navigate to the content editor and select the view that contains the entry you want to duplicate.
2. Click on the entry to edit it.
3. Click on the duplicate icon at the top of the screen.
4. The duplicated entry loads. The word **(copy)** at the end of the title line indicates that you're currently in a copy of the original entry. You can now make the necessary changes to the content entry.
5. Click `Save` or `Save & publish` depending on your workflow. If you try to leave without saving, the system will warn you.

<Alert theme="warning">
The system adds the word **(copy)** at the end of fields marked as `Title` in the schema.

![Use as title field - Schema field configuration](/images/docs/user-guides/use-as-title-field.png)

Check out our [Field configuration](/docs/api-reference/schema/field-configuration#use-as-title-field) document for more information about this.
</Alert>

Note that if the content entry contains reference fields, some of the relations will be duplicated and others won't. The system will notify you if this is the case:

![References not duplicated](/images/docs/user-guides/references-not-duplicated.png)

What is copied in this case is the reference - the link between the two content pieces - but not the referenced entry itself.

The following table explains the system behavior depending on reference configuration:

| Type                          | Direction         | Cardinality  | System behavior                                                           |
| ----------------------------- | ----------------- | ------------ | ------------------------------------------------------------------------- |
| Can reference only one model  | One-way reference | To one       | The system duplicates the reference.                                      |
| Can reference only one model  | Two-way reference | One to one   | The system **does not duplicate** the reference. You can add it manually. |
| Can reference only one model  | One-way reference | To many      | The system duplicates the reference.                                      |
| Can reference only one model  | Two-way reference | Many to many | The system duplicates the reference.                                      |
| Can reference multiple models | Two-way reference | One to one   | The system **does not duplicate** the reference. You can add it manually. |
| Can reference multiple models | Two-way reference | Many to many | The system duplicates the reference.                                      |
| Can reference multiple models | Two-way reference | Many to one  | The system duplicates the reference.                                      |

<Alert theme="info" title="Pro Tip">
The system will not duplicate references with the cardinality **one to one**.
</Alert>

## Duplicate relations

When viewing content that has relations (references), you can quickly duplicate referenced entries within an original entry. This is a quick way to keep the format of the related content, while allowing you to make content edits that won't affect other entries that contain the same reference.

![Duplicating related content](/images/docs/user-guides/duplicating-related-content.png)

1. Navigate to the content entry that contains the relation you want to duplicate.
2. Click on the context menu and select `Duplicate`.
3. The duplicated reference screen will display. Here you can make the necessary edits, then click `Save` or `Save & Publish` depending on your workflow.
4. Click on the `X` at the top-left corner of the editor to return to the original content entry you were working on. The reference field now contains the duplicated reference.

    <Alert theme="warning">
    System behavior depends on field configuration:

    - If the field allows referencing only one model, the duplicate will replace the original.

    - If the field allows referencing more than one model, the duplicate will display as an additional reference.
    </Alert>


---
# Publishing content

Source: https://hygraph.com/docs/developer-guides/content/publishing-content

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on mutations](/docs/api-reference/content-api/mutations#publishing-content-mutations)

</Alert>

## How to publish content

Publishing content is in some ways the most important step of creating effective content. If it is not published, no one can consume the content that you've created.

Hygraph has two [Content Stages](/docs/developer-guides/content/content-stages) as we've seen before, `DRAFT` and `PUBLISHED`. When you have finished working on a content piece and would like to move it out of the `DRAFT` stage and into the `PUBLISHED` stage, simply click `Save & Publish` or `Publish`.

<Alert theme="info" title="Pro Tip">
- If the latest changes have not yet been saved, the button will say `Save & Publish`.
- If the latest changes have already been saved, the button will say `Publish`.
</Alert>

One thing to always check is that all of the assets and references are also on the `PUBLISHED` stage so that everything loads properly.

If Hygraph notices that assets or relations to your content are still in the `DRAFT` stage, clicking `Save & Publish` will prompt you to publish these too.

When content is `PUBLISHED`, the system creates a new version so you can see how it has evolved and when it was last updated.

<Alert theme="info">
If you have additional stages enabled, you will be presented with a dropdown to choose which stage you want to publish to.
</Alert>

![Publishing to a stage](/images/docs/user-guides/publish-to-content-stages.png)

## Edit published content

Once published, any content can be edited in a similar fashion to [creating new content](/docs/developer-guides/content/creating-content). Simply navigate to the content piece you would like to modify, and use the content editor as before.

When changes are made to the content, you will see the `Save & Publish` button has been reactivated, allowing you to publish the changes you've made. If you choose to retain the changes in the `DRAFT` stage and not publish them, you will need to click on the `Save` button instead.

You will notice that the pill for that content in the content table has changed to blue, indicating [outdated content](/docs/developer-guides/content/publishing-content#outdated-content). This implies that changes have been made on the `DRAFT` stage that have not yet been promoted to the `PUBLISHED` stage.

## Outdated content

With Hygraph it is possible to review posts that have been published beforehand, and have changes made on the `DRAFT` stage.

![Outdated Content Warning](/images/docs/user-guides/outdated-content-warning.png)

When looking at the content view, a new blue pill indicates that a previously `PUBLISHED` content piece has changes that were saved on the `DRAFT` stage, but not on the `PUBLISHED` stage.

Once reviewed and approved by the Editor, clicking `Publish` will promote the new changes to the `PUBLISHED` stage.

To compare the changes made on `DRAFT` to the `PUBLISHED` state, simply navigate to the available versions in the right sidebar.

![Compare current draft](/images/docs/user-guides/compare-with-current-draft.png)

Click [here](/docs/developer-guides/content/content-stages) to learn more about content stages.

## Scheduled publishing

**Hygraph** allows you to schedule content publishing and unpublishing, as one off or as a collection - referred to as a "release".

Check out our document on [scheduled publishing](/docs/developer-guides/content/scheduled-publishing) to learn more.


---
# Rich Text editor

Source: https://hygraph.com/docs/developer-guides/content/rich-text-editor

## Overview

This content editor tool comes out-of-the-box for all Hygraph projects, and provides great flexibility when it comes to creating, editing, and manipulating content entries showcasing text and images.

If your project schema is configured so that your model has a Rich Text field, you'll see it like this in the content editor:

![Rich Text editor](/images/docs/user-guides/rte/rte-ui-buttons.png)

1. This dropdown allows you to format text you've highlighted in the text area. You can format it as normal text as well as different heading levels.
2. These typography options allow you to make text bold, italic, or underlined.
3. Use this option to add a link. Click [here](/docs/developer-guides/content/rich-text-editor#links) for more information.
4. Use this option to format the text as a block quote.
5. Use this option to format the text as inline code.
6. This option allows you to include an asset. Click [here](/docs/developer-guides/content/rich-text-editor#assets) for more information.
7. Use these options to create either a bulleted or numbered list.
8. Use this option to format the text as a code block.
9. Click on the `Iframe` button to display a popup where you can enter an iframe URL. After you've entered a valid iframe URL, click on the `OK` button to add it to your content.
10. Use this option to assign classes to your text. Simply highlight the text and click on the `Class` button. A popup will display for you to type in the `Class name`, then click on `Ok` to finalize the process.
11. Use this option to add a table.
12. Use this option to format text as subscript.
13. Use this option to format text as superscript.
14. Use this option to enter the fullscreen rich text editor mode.
15. This option allows you to embed content from a model. Click [here](/docs/developer-guides/content/rich-text-editor#embeds) for more information.


<Alert theme="info" title="Are you looking for our API Reference?">
[Check out our API Reference document on Rich Text](/docs/api-reference/content-api/rich-text-field)
</Alert>

## Field configuration

![Rich Text editor configuration](/images/docs/user-guides/rte/rte-config.png)

When you add a Rich Text field to a model in your schema, you will find the following options:

| Tab         | Field Name                | Description                                                                                                                                                                                              |
| ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | `Display Name`            | Display name of your rich text field.                                                                                                                                                                    |
| Settings    | `API ID`                  | API ID of your Rich Text field. This field is autocompleted as you type in the display name, but can be edited.                                                                                          |
| Settings    | `Description`             | Optional field. You can add a description for your Rich Text field here.                                                                                                                                 |
| Settings    | `Enable embedding`        | Select this checkbox to enable embedding, which will allow you to reference content inside rich text. You cannot edit this setting after the initial save.                                               |
| Settings    | `Allow multiple values`   | Select this checkbox to store a list of values instead of a single one.                                                                                                                                  |
| Settings    | `Localize field`          | Select this checkbox to make the Rich Text field localized.                                                                                                                                              |
| Settings    | `Formatting options`      | Use this dropdown menu to customize which buttons will appear in your rich text editor. You can read more about this menu [here](/docs/developer-guides/content/rich-text-editor#customize-your-editor). |
| Validations | `Make field required`     | Select this checkbox to make the rich text field required. If you select it, you won't be able to save the entry if the field is empty. This option cannot be edited after the initial save.             |
| Validations | `Set field as unique`     | Select this checkbox to set this field as unique. Selecting it ensures that multiple entries can't have the same value for this field.                                                                   |
| Advanced    | `Set initial value`       | Select this checkbox to set an initial value to prefill the form input.                                                                                                                                  |
| Advanced    | `Show based on condition` | Select this checkbox to set condition visibility for this field. [Check out our conditional fields document to learn more](/docs/developer-guides/schema/conditional-fields).                            |
| Advanced    | `Field visibility`        | Use this dropdown to select a field visibility option. The options are: read/write, read only, hidden, and API only.                                                                                     |

### Customize your editor

When you configure your Rich Text field, you will find the `Formatting options` under **Settings**.

![Rich Text editor configuration](/images/docs/user-guides/rte/rte-config-buttons.png)

This dropdown menu lets you select which buttons will display on your rich text field in the **Content editor**.

![Rich Text editor configuration](/images/docs/user-guides/rte/rte-config-buttons-displayed.png)

By default, all checkboxes are selected. Deselect the buttons that you don't want in your rich text editor.

<Alert theme="info" title="Pro Tip">

You can change your formatting options after the initial save.

To do this, simply edit your Rich Text field and select/deselect the checkboxes according to your needs.

</Alert>

## Using the Rich Text editor

### Links

Click on the `Link` button to display the **Insert link** popup, which contains two tabs: **Settings** and **Attributes**.

#### Settings

![RTE - Insert link - Settings tab](/images/docs/user-guides/rte/rte-links-settings.png)

- **Link type:** Use the radio buttons to select one of the two options. Your selection modifies the fields displayed on screen.
  - **URL:** Select this option to add a link to an external source.
  - **Entry:** Select this option to add a link to an entry in your Hygraph project.
- **Link text:** You can add text for your link in this field. If you are creating a `URL` link type and don't complete this field, the **Link address** will be used as **Link text**. This field becomes mandatory for the `Entry` link type. If you selected text before clicking on the link button, this field will be autocompleted with the selected text.
- **Link address:** Mandatory field where you can type the URL you wish to link to. This field only displays for the `URL` link type.
- **Open link in new tab:** Use this checkbox for your link to open in a new tab. It adds the `target='_blank'` attribute to your link. This field only displays for the `URL` link type.
- **Link title:** Optional field where you can enter a tooltip to display on hover. This field only displays for the `URL` link type.
- **Select entry:** Click on `Add existing entry` to select the entry in your Hygraph project that you wish to create a link to. Only models that can be embedded will display in the dropdown. This field only displays for the `Entry` link type.
  - **Select entry** with an **Asset** creates a text-based link that references the asset entry. It does not wrap an inserted or rendered image in a link.
- **Action buttons:**
  - **Cancel:** Click on this button to cancel the process.
  - **Insert:** Click on this button to save the link and add it to your content entry.

#### Attributes

You can optionally complete the following `HTML` attributes:

![RTE - Insert link - Attributes tab](/images/docs/user-guides/rte/rte-links-attributes.png)

- **Rel attribute:** This attribute defines the relationship between the current document and the linked resource.
- **Class attribute:** This attribute specifies one or more `classnames` for an element. You can add classes separated with spaces here.
- **ID attribute:** This attribute is used to specify a unique `id` for an `HTML` element.
- **Action buttons:**
  - **Cancel:** Click on this button to cancel the process.
  - **Insert:** Click on this button to save the link and add it to your content entry.

### Assets

Clicking on the `Assets` button opens the **Select Asset** screen:

![RTE - Select assets](/images/docs/user-guides/rte/rte-assets-select.png)

Select an asset by clicking on the purple reference icon located at the beginning of each asset entry. This will automatically add the asset to your content.

If the asset you need has not yet been uploaded to your project, you can do so from here by click on the `Upload` button. This process follows the standard [asset upload flow](/docs/developer-guides/assets/upload-asset).

### Embeds

Use this option to create **inline** and/or **block embeds**.

**Inline embeds** give Content Creators maximum flexibility to add references or relations directly within the text so they can move faster. This also clears up clutter around content creation, so they are able to add things like authors, citations, product attributes and more without having to add extra fields within the content entry.

**Block embeds** give Content Creators more flexibility with less clutter. Use block embeds to insert assets and other models inside the text as a block. This can be useful when adding images like logos, or referencing audiences to previous created material that support the new content item like blog posts, documents, announcements, etc.

![RTE - Embeds - Block embed screen example](/images/docs/user-guides/rte/rte-block-embed.png)

<Alert theme="warning">
Only the content from the selected models in the Rich Text field configuration is available to be embedded. To be able to embed content from more models, enable them from the Rich Text field settings in the schema builder.
</Alert>

Whether you add an inline or a block embed, both screens show the same options: Use the dropdown to select the model you wish to embed content from, then click on `Select model`.

The system will display the selection screen for the chosen model. To select an entry and add it to your content, simply click on the purple reference icon located at the beginning of each content entry.

To `Edit` or `Remove` an embed you've added to your Rich Text editor, click on the context menu icon of your embed and select the desired option.

## Resources

- [Rich Text field API Reference:](/docs/api-reference/content-api/rich-text-field) Guide for developers on how to work with the Rich Text field.
- <Link href="https://hygraph.com/blog/hygraph-react-rich-text-renderer" target="_blank">Introducing the Hygraph React Rich Text Renderer:</Link> Blog post on how to render Hygraph documents using Rich Text in your application easily using our available packages.
- <Link href="https://hygraph.com/blog/styling-rich-text-tailwindcss" target="_blank">Styling Rich Text with TailwindCSS:</Link> Detailed tutorial on how to use the `JSON` representation from the RTE to create custom elements for each text-based element of Rich Text.


---
# Scheduled publishing

Source: https://hygraph.com/docs/developer-guides/content/scheduled-publishing

## Overview

<Alert theme="warning" title="Feature availability">
This feature is only available for **Enterprise** plans. Please [contact sales](/contact) for further information.
</Alert>

Hygraph gives you the ability to schedule content publishing, and unpublishing as a one-off or as a collection,referred to as a "release".

| Section           | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| Scheduled entries | Overview of all individually scheduled items that are not part of a release. |
| Releases          | Overview of all releases, and their scheduled items.                         |

Scheduled entries in the content table display a stage pill with a clock on it:

![Scheduled entries in the content table](/images/docs/user-guides/scheduled-entries-pill.png)

Hovering over the pill will show you schedule publishing information for that entry.

![Scheduled entries in the content table](/images/docs/user-guides/scheduled-entries-pill-hover.png)

## How to schedule

When editing a content entry, instead of publishing right away, you can **Schedule** an entry for publishing at a later date & time.

You can find this option inside of the dropdown on the **Publish** button.

![Schedule Item Dropdown](/images/docs/user-guides/schedule-item-dropdown.png)

The screen will guide your through the scheduling process, where you can create a one-off scheduled release, bundle it with other scheduled entries, or create a new release to add it.

![Scheduling Options](/images/docs/user-guides/schedule-item-modal.png)

### Schedule entry only

You can publish (or unpublish) individual content entries at a specified date and time by selecting the `Schedule entry only` option.

![Schedule Item](/images/docs/user-guides/schedule-item.png)

1. Use the radio buttons to select the `Action` - if the entry should be published, or unpublished.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

2. Click on the calendar icon under `Date and time` to select when the entry should be published. Alternatively, you can manually type in the date in the format that's visible in the placeholder of the field.
3. Use the `Timezone` dropdown to select one of the available timezones.
4. Use the checkboxes to select which localizations should be included. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.
5. If you have any references linked to the entry you are scheduling, you can schedule those individually too.

![Schedule Related Entries](/images/docs/user-guides/schedule-relations.png)

### Add to an existing release

You can bundle multiple content entries into a single release that will be published (or unpublished) at a specified date and time.

Your releases will be shown if you choose to **Add item to a release**:

![Schedule release](/images/docs/user-guides/schedule-release.png)

1. Use the `Release` dropdown to select the release you want to add this entry to.
2. Use the radio buttons to select the `Action` - if the item should be published, or unpublished.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

3. Use the checkboxes to select which localizations should be included. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.

### Add to a new release

You can create a new release to add the current entry to by selecting `Add to a new release`:

![Schedule release](/images/docs/user-guides/add-to-new-release.png)

1. Give the new release a `Name` and, optionally, a `Description`.
2. Use the radio buttons to select the `Action` - if the entry should be published, or unpublished.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

3. Click on the calendar icon under `Date and time` to select when the entry should be published. Alternatively, you can manually type in the date in the format that's visible in the placeholder of the field.
4. Use the `Timezone` dropdown to select one of the available timezones.
5. Use the checkboxes to select which localizations should be included.
6. If you have any references - such a images - linked to the entry you are scheduling, you can use the checkboxes to schedule those too.

![Schedule Related Entries](/images/docs/user-guides/schedule-relations.png)

## Scheduled entries

You can find the scheduled entries table in `Content > Schedule > Entries`.

![Scheduled entries table](/images/docs/user-guides/scheduled-entries-table.png)

If you have no scheduled entries, the screen displays an empty state containing a link to the content editor, where you can select entries to schedule.

### View scheduled entries

Navigate to `Content > Schedule > Entries` to view the table of scheduled entries.

![View scheduled entries](/images/docs/user-guides/view-scheduled-entries.png)

The table contains all individual entries that have been scheduled. It can be sorted by newest, with most recently scheduled entries displaying at the top of the table, or oldest. To sort entries, click on the `Target date` column header.

![Scheduled entries - Target date](/images/docs/user-guides/scheduled-entries-target-date.png)

You can filter the entries table by publication status: All, Completed, Failed, and Pending. To filter entries, use the dropdown at the top of the table.

![Scheduled entries - Filter by status](/images/docs/user-guides/scheduled-entries-sort-status.png)

If the process fails, you can scroll over the `Failed` status to get more information:

![Scheduled publication failed](/images/docs/user-guides/scheduled-failed.png)

The modal gives you the option to copy the error or contact support.

### Remove scheduled entries

Navigate to `Content > Schedule > Entries` to remove scheduled entries.

Use the checkboxes to select one or more entries, and click `Remove` on the action bar that display at the bottom of the table.

![Remove scheduled entries](/images/docs/user-guides/remove-scheduled-entries.png)

You will need to confirm this action, as deletion cannot be rolled back.

## Scheduled releases

You can find the scheduled releases table in `Content > Schedule > Releases`.

![Scheduled releases table](/images/docs/user-guides/scheduled-releases-table.png)

If you have no scheduled releases, the screen will display an empty state prompting you to add a release.

### Add a release

If you want to schedule a group of entries to be published (or unpublished) at the specified day and time, you can add a release.

To do this, navigate to `Content > Schedule > Releases` and click **+ Add release**:

![Releases overview](/images/docs/user-guides/releases-overview.png)

You'll need to give it a name, and an optional description. At this time, you can also use the dropdown menus to select a date & time, and a timezone:

![Create release](/images/docs/user-guides/create-release.png)

To finalize the process, click `Add` to save. The scheduled release will display on the releases table.

<Alert theme="info" title="Pro Tip">

Any changes to your `DRAFT` content will be included with any pending scheduled release(s).

</Alert>

### Edit a release

To edit a release, navigate to `Content > Schedule > Releases`, select the context menu of one of the releases on the table, and click `Edit`.

![Edit a release](/images/docs/user-guides/scheduled-release-edit.png)

Simply edit the details as needed, and then click `Update`.

### Delete a release

To delete a release, navigate to `Content > Schedule > Releases`, select the context menu of one of the releases on the table, and click `Delete`.

![Edit a release](/images/docs/user-guides/scheduled-release-delete.png)

Since it's not possible to roll back deletions, you'll need to confirm this action to finalize the process.

## Limits

- The following limits are set per your plan and can be customized:
    - A maximum of 50 pending releases, and 50 items in a single release.
    - A maximum of 200 pending scheduled items overall within your project environment.
- The date and time selected for a release can't be in the past.


---
# Searching for content

Source: https://hygraph.com/docs/developer-guides/content/searching-for-content

The most basic feature for navigating the content is using the search.

The Search function enables you to quickly find any pieces that match the keyword entered. Users are able to search for any keyword (string fields) used in the content piece, such as Author, Title or Content Keywords.

![Search for content](/images/docs/user-guides/search-filter.png)

By submitting a search term, a fresh request is generated including a `where` argument.

Specifying a field type to narrow down the search can be done by typing the first letters or selecting it accordingly in the filter bar. The search itself is not case sensitive, meaning `TEST` or `test` will return the same results.

<Alert theme="info">
Hygraph does not support Full Text Search currently. Rich Text or JSON is currently not supported. It's also not possible to filter or search for multi-value fields, colors, and coordinates.
</Alert>

The default order of the items is by "created at", starting with the oldest item. Sorting by "created at" will allow you to change the order.

```graphql
{
  posts(where: { _search: "Test" }) {
    id
  }
}
```

In addition, it is possible to specify the following field types as part of the search request:

- String (Single-Line, Multi-Line, Slug, Markdown)
  - also multi-value versions of these
- Float
- Integer

An editor can verify the schema of the content model to understand which field types are used. However, the usable field types will be shown in the search bar as part of the filters and depend on the schema modeling. The advantage of specifying a field type lies in a performance improved search - which can be useful on larger content projects.

The following field types that can be used as additional filters.

- Enumeration
- Boolean

Mixing the different searches and filters will create more granular results. Note that conditions of all filters apply, meaning that the search query is of an AND-type.
Editors also have the capability to save the search/filter as a content view.

## Additional resources

- [Using filters](/docs/developer-guides/content/using-filters): Learn how to filter content by entry, relations, and content stage.


---
# Updating content

Source: https://hygraph.com/docs/developer-guides/content/updating-content

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on mutations](/docs/api-reference/content-api/mutations#update-entries)

</Alert>

## How to update content

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvxshv5h07vx2sy9mqw8" caption="Content List Overview" />

1. Navigate to the **Content editor**.
2. Select a content model.
3. Find the content item you want to edit on the table and click on it to enter content editing mode.
4. Edit the content and then click `Save` to save the newly edited content in the `DRAFT` stage, or click `Save & Publish` to move the content to the `PUBLISHED` stage.

<Alert theme="info" title="Pro Tip">
Content in Hygraph that has been saved but has never been published, exists only in the `DRAFT` stage.

When promoted to the `PUBLISHED` stage, content will exist in that stage, and also in `DRAFT`.

When you update a content entry and save without publishing, that new content will be saved in `DRAFT` and the entry will show a blue `Published` pill on the content table, indicating that it's **outdated**.

Content being **outdated** means that the version currently saved in the `DRAFT` stage contains changes that have not yet been promoted to `PUBLISHED`.
</Alert>


---
# Using filters

Source: https://hygraph.com/docs/developer-guides/content/using-filters

## Overview

Filtering allows you to restrict the content shown by specific parameters. This is helpful when trying to create a more curated overview of content.

<Alert theme="warning">
Hygraph does not currently support filtering for Rich Text (even if inside components), JSON, multi-value fields, colors, or coordinates.
</Alert>

These filters can be useful when building content views, looking for a specific type of content, or finding content that matches several parameters, such as "`Created by` a certain user & `Stage` published".

<Alert theme="info" title="Are you looking for our API Reference?">
[Check out our API Reference document on filtering](/docs/api-reference/content-api/filtering)
</Alert>

## Quick Filters

Our **Quick Filters** feature reduces the time and effort required to create a filter. Editors can now find the content they need, faster.

![Quick Filters](/images/docs/user-guides/using-filters/quick-filters.png)

It offers several predefined filters that apply instantly when selected, allowing editors to focus on their work without unnecessary distractions.

<Alert theme="info" title="Pro Tip">

Quick Filters are available in both regular content views and asset views.

</Alert>

**To add Quick Filters**, simply use the `Filter` menu to display the available options and select one.

![Add a Quick Filter](/images/docs/user-guides/using-filters/add-quick-filters.png)

Once you select a Quick Filter, the regular filter appears in the filter bar and the content table is sorted accordingly.

You can apply more than one Quick Filter. To do this, simply use the filter menu again and select another one.

For instance, the following image shows a content table where two Quick Filters have been applied, `Created by me` & `Only published entries`:

![Quick Filter applied](/images/docs/user-guides/using-filters/quick-filter-applied.png)

<Alert theme="info" title="Pro Tip">
Quick filters are commonly used filter configurations that offer a shortcut to finding the content you're looking for. Once applied, you can use them as they are, or [edit them](/docs/developer-guides/content/using-filters#adjust-filters-manually).
</Alert>

## Column filters

The `Filter` menu also contains column filters.

![Column filters](/images/docs/user-guides/using-filters/column-filters.png)

Column filters allow you to filter content by some system and custom fields, stage and ID.

Quick and column filters function in the same way. [The following document section](/docs/developer-guides/content/using-filters#adjust-filters-manually) explains how to use them.

## Adjust filters manually

You can find the filters on any content view, at the top of the content table. If there are no filters added, this is how it will look like:

![Filter Bar](/images/docs/user-guides/filterbar.png)

**To apply filters:**

1. Navigate to the **Content Editor** & select a view from the collapsible sidebar.
2. Click the `Filter` button at the top of the content table.
3. Select one of the fields listed for filtering. It can be a quick or column filter.
    - **If you selected a quick filter**, the results will show on the table below.
    - **If you selected a column filter**, you need to configure it:
            - Select a condition. [This document section explains what each condition does](/docs/developer-guides/content/using-filters#filtering-conditions).
            - Enter a comparison value in the input to the right of the filter method.

<Alert theme="info" title="Pro Tip">
You can use the `Search` at the top of the filters menu to quickly find a filter.
</Alert>

For example, the following image shows that we have selected to filter by `ID`, then selected the condition `contains`, and finally we typed "002" in the input. As a result, the filter shows all entries that have an ID containing 002:

![Filter example](/images/docs/user-guides/filter-example.png)

**To remove a filter**, simply click the `X` button next to it.

![Remove filter](/images/docs/user-guides/remove-filter.png)

### Filtering by entry

After applying a quick or column filter, the results will display on the table below. The following example shows the `Created By` filter applied:

!["Created By" filter applied](/images/docs/user-guides/createdby-filter.png)

You can adjust these filters manually by using the input fields or dropdown menus, and you can add additional filters by clicking on the filter icon.

![Apply a Filter](/images/docs/user-guides/filters-icon.png)

Additionally, you can also filter by fields that allow multiple values. Here's an example showing an enumeration field for product size:

![Multi-value enum filtering](/images/docs/user-guides/multivalue-filter.png)

### Filtering by relations

To filter your content entries by a reference field, click the `Filter` button and select the reference field from the column filters list.

<Alert theme="warning">
**It is not possible to filter by union-type reference fields** - those that allow you to reference more than one model in a field.
</Alert>

To configure the filter:

1. Select the field of this model that you want to use.
2. Select a [condition](/docs/developer-guides/content/using-filters#filtering-conditions) from the dropdown menu.
3. Some conditions will require that you type in some data to filter by, such as a name or a slug. `Updated At` and `Created At` require that you select a date from a calendar and type in a time. `Is null` and `Is not null` do not require any additional input.

The following example [filtering condition](/docs/developer-guides/content/using-filters#filtering-conditions) shows `all` of the content entries where the "Other products" reference field links to entries with a `Slug` that contains `tote`.

![Filtering by relations](/images/docs/user-guides/relational-filter.png)

<Alert theme="info" title="Pro Tip">

The default reference filters that all projects have are `Created by`, `Updated by`, and `Published by`. They are related to project users and provide relational fields that you can select from the condition dropdown.

You can also filter by custom reference fields created for your project, as long as they are not union fields.

[Our Editor Guides contain detailed information all reference filters available.](/docs/editor-guides/content/filter-content#reference)

</Alert>

### Filtering by content stage

To filter content by stage, click the `Filter` button at the top of the content table, and select `Stage` from the column filters list.

After this, use the dropdown menus to select a condition and stage.

![Filtering by content stage](/images/docs/user-guides/content-stage-filtering.png)

#### Stages and conditions

While there are three default stages - `DRAFT`, `PUBLISHED`, and `PUBLISHED (!)` - stages other than the default ones can exist in the projects of Growth and Enterprise plans.

| Stage Name             | Definition                                                                                                                                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DRAFT`                | Content entries that exist in `DRAFT`, and don't exist in any other stage. This content has never been published.                                                                            |
| `PUBLISHED`            | Content entries that exist in `PUBLISHED` and are not outdated. This means that the published version of this content is also the latest version on the system.                              |
| `PUBLISHED (!)` | Content entries that exist in `PUBLISHED` but are outdated. This means there is a version of this document currently published, but there is also another more recent version in the system. |

<Alert theme="warning">
Please take into account that our stages are not linear and sequential. There are cases where content can be in more than one stage at the same time, such as PUBLISHED and QA. This would happen if, for instance, you edit an already published document, but select the QA stage from the dropdown upon publishing your changes.
</Alert>

| Condition         | Definition                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `is`              | Select this condition to fetch content entries that only exist in the selected stage.                                                                                                                              |
| `is not`          | Select this condition to fetch content entries that do not exist in the selected stage, and only exist in one stage.                                                                                               |
| `contains`        | Select this condition to fetch content entries that exist in the selected stage, irrespective of also existing in other stages. **This condition will only display for projects with more than two stages**.       |
| `doesn't contain` | Select this condition to fetch content entries that don't exist in the selected stage, irrespective of also existing in other stages. **This condition will only display for projects with more than two stages**. |

<Alert theme="info" title="Pro Tip">
Filtering can also be applied to your project's custom filters.

Custom filters creation will result in a state that can be updated or outdated, and the behavior will be the same as the updated/outdated behavior shown above for `PUBLISHED` and `PUBLISHED (Outdated)`.
</Alert>

## Filtering conditions

The following list explains basic conditions and what they do:

| Option                     | Description                                               |
| -------------------------- | --------------------------------------------------------- |
| `Is`                       | Exact match                                               |
| `Is Null`                  | Matches empty (without content)                           |
| `Is Not Null`              | Matches not null (with any content added)                 |
| `Is Not`                   | Exclusion match                                           |
| `Less Than`                | for numeric fields (including date and dateTime)          |
| `Less Than or Equal To`    | for numeric fields (including date and dateTime)          |
| `Greater Than`             | for numeric fields (including date and dateTime)          |
| `Greater Than or Equal To` | for numeric fields (including date and dateTime)          |
| `Contains`                 | String search                                             |
| `Doesn't Contain`          | Exclusion by string search                                |
| `Starts With`              | Starting string match                                     |
| `Doesn't Start With`       | Exclusion by starting string match                        |
| `Ends With`                | Ending string match                                       |
| `Doesn't End With`         | Exclusion by ending string match                          |
| `Includes some`            | for multi-value fields, some of the provided values match |
| `Includes all`             | for multi-value fields, all of the provided values match  |
| `Includes none`            | for multi-value fields, none of the provided values match |

<Alert theme="info">

[Our Editor Guides contain detailed information about all the different types of filters available.](/docs/editor-guides/content/filter-content#general-filter-conditions)

</Alert>

---
# Using references

Source: https://hygraph.com/docs/developer-guides/content/using-references

## Overview

References connect two or more content entries in Hygraph.

This document gets into how to use the different reference types in the Hygraph app.

<Alert theme="warning">

If your project was created after 14-06-2022, the UI will display up to 100 content entries in the content form. For projects created before that, it will display up to 500.

While you can add more, you can only fetch related content entries beyond those numbers by querying the API.

</Alert>

## What you can do

- You can use the reference field in the **Content editor** to connect content entries to one another according to schema configuration.

Examples of this could be linking an **Author** to a **Blog Post**, or a **Category** to a **Product**.

## Reference types

There are four types of references based on how many entries you can link and in which direction:

- **One-to-one references:** They connect one entry to one other entry from a specific model. For example, a country can have one capital, and a capital belongs to only one country.
- **One-to-many references:** They link one entry to multiple entries from a specific model. For example, an author can be linked to many blog posts.
- **Many-to-many references:** They allow multiple entries to connect to multiple other entries, but only within the allowed models. For example, a product can belong to multiple categories, and a category can contain multiple products.
- **Many-to-one references:** They let multiple entries from specific models link to a single entry from a configured model. For example, many blog posts can reference the same author.

<Alert theme="info">

When configuring a reference field, you must choose which content models can be linked. You cannot reference just any entry. Learn more about this in our [reference configuration](/docs/developer-guides/schema/references) documentation.

</Alert>

## How to use references

References are used in similar ways, irrespective of their type. In general terms, you have the option to add an existing content entry, or create & save a new one.

Depending on reference type and configuration, you may have to select a model before you can select an entry, and then you will be able to select one or more content entries to relate to the parent entry.

Here is a detailed explanation on how to work with each reference type:

### One-to-one references

<VideoEmbed videoId="k_TzxM63vpI" />

Click `Add existing <model_name>` to pick a content entry from an allowed model configured in the schema. Select an entry, then return to the content editor, where it will appear as a reference.

Click `+ Create new <model_name>` - called `+ Create & replace <model_name>` if you have already selected an existing entry - to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The model available for selection is preconfigured in the **Schema**. Check out our [References](/docs/developer-guides/schema/references) document to learn more about reference configuration.

### One-to-many references

<VideoEmbed videoId="W-6tUCSjrzA" />

Use the `Add existing <model_name>` button to select one or more content entries from a preconfigured model. Simply click on the checkboxes of the entries you want to reference in order to select them, then click on `Add selected <model_name>`. You will then return to the current content creation screen, and will find the selected entries added as references.

Click `+ Create new <model_name>` to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The model available for selection is preconfigured in the **Schema**. Check out our [References](/docs/developer-guides/schema/references) document to learn more about reference configuration.

### Many-to-many references	

<VideoEmbed videoId="3y14YhnILl4" />

Use the `Add existing entries` button to select from the preconfigured models available in the schema. Click on a model name to select entries from that model. Use the checkboxes of the entries you want to reference to select them, then click on `Add selected entries`. When you return to the content editor, they will appear as references.

You can optionally click on `Add existing entries` again to add more entries from the same model or from a different one.

You can also use the `+ Create new entry` to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The models available for selection are preconfigured in the **Schema**. Check out our [References](/docs/developer-guides/schema/references) document to learn more about reference configuration.

### Many-to-one references

<VideoEmbed videoId="LUI3m5zEZsM" />

Use the `Add existing entries` button to select from the preconfigured models available in the schema. Click on a model name to select an entry from that model, and use the reference icon to select & add one. When you return to the content editor, they will appear as references.

Click `+ Create new entry` - called `+ Create & replace entry` if you have already selected an existing entry - to create, save and relate a new content entry. After saving, it will appear as a reference in the content editor.

The models available for selection are preconfigured in the **Schema**. Check out our [References](/docs/developer-guides/schema/references) document to learn more about reference configuration.

## Conditional references

If the reference field has `Conditional visibility` configured, it will only display in the content form when the condition is met.

You can find out if a reference field has a condition configured by looking at the `Conditional visibility` checkbox in the `Configure` section of your reference configuration screen:

![Conditional references](/images/docs/user-guides/conditional-reference.png)

[Check out this document to learn how conditional visibility works.](/docs/developer-guides/schema/conditional-fields)

## Related documents

- [References:](/docs/developer-guides/schema/references) This document explains how to configure the different types of references in the schema builder.
- [Components or references?:](/docs/developer-guides/schema/components-or-references) This document explains how to choose between a reference or a component depending on your content.
- [Reference field type:](/docs/api-reference/schema/field-types#reference) API Reference document on reference configuration. Use this document to configure references through the API.

---
# Versioning content

Source: https://hygraph.com/docs/developer-guides/content/versioning-content

## Overview

Content versioning lets you track changes in published content over time. When versioning is enabled, a new version is created with each published change.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xausjawf07w5hpa78xlh" caption="Version comparison in Hygraph" />

The number of saved versions depends on your Hygraph plan.

New versions are created when you publish content to any stage. `DRAFT` content is not versioned, and its revision history is not available. Version history is only retained for content published to other stages.

<Alert theme="warning">
- Versioning is available on paid plans only.
- Versions do not store assets or referenced entries. In those cases, only the link between a content version and its assets or related entries is preserved. This means that if you delete them, you won't be able to restore them using version comparison.
</Alert>

## How versions are created

Versions are automatically generated whenever a content entry is edited and published. It ensures that each published change is saved as a new version.

You can find the list of versions in the **Versions** section of the right sidebar.

![Versions section on the sidebar panel](/images/docs/user-guides/content-versions-panel.png)

[Learn more about Publishing content](/docs/developer-guides/content/publishing-content).

## Version comparison & restoration

Users can compare versions across [content stages](/docs/developer-guides/content/content-stages) to track changes over time. If editors need to revert updates from the `PUBLISHED` stage back to `DRAFT`, they can review both versions side by side and select specific fields to restore.

It helps content teams avoid duplicate work when rolling back changes.

![Version comparison - Comparison view](/images/docs/user-guides/version-comparison-view.png)

To compare and restore versions:

1. Open a content entry to compare versions.
2. Find the `Versions` section on the right contextual sidebar and click on the version you want to compare the currently published version to.
3. A split-pane window shows both versions side by side: the published version on the left and the draft on the right. The content is separated into the individual fields configured for the model in your schema. The right panel shows an `Edited` pill next to the fields that are different from the draft version for easy identification. To restore a field, hover over it and click `Restore`. To restore all changes, click `Restore all changes` at the top-right of the screen.
4. Click `Apply changes` to go back to the content form, where the entries you selected show the restored content.

When you click `Save & Publish`, the system will generate a new version including the latest changes.

---
# Hygraph code examples

Source: https://hygraph.com/docs/developer-guides/hygraph-code-examples

Here is a list of our most recently updated code examples:

| Example name                                                                                                              | Description                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-algolia" target="_blank">Algolia</Link>                                           | This example demonstrates how to use Hygraph webhooks to sync data to Algolia on new published content.                                                                                                                                                                      |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-apollo-client-3" target="_blank">Apollo Client 3</Link>                           | This example demonstrates how to query from Hygraph with `graphql-request` in `React.js`.                                                                                                                                                                                    |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-apollo-server" target="_blank">Apollo Server</Link>                               | This example demonstrates how to use `apollo-datasource-graphql` to pull a Hygraph schema into an existing Apollo Server.                                                                                                                                                    |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-astro" target="_blank">Astro</Link>                                               | This example demonstrates how to use the Astro with Hygraph.                                                                                                                                                                                                                 |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-asset-upload" target="_blank">Asset upload example</Link>                        | This example demonstrates how to programmatically import assets from a URL using the Asset Upload endpoint. Uses Bee-Queue to process jobs (recommended for large data imports).                                                                                             |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-eleventy" target="_blank">Eleventy</Link>                                         | This example demonstrates how to use the Eleventy and GraphQL Request with Hygraph.                                                                                                                                                                                          |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-express" target="_blank">Express</Link>                                           | A simple Express app using `ejs` templating and `awesome-graphql-client`.                                                                                                                                                                                                    |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-genql" target="_blank">GenQL</Link>                                               | This example demonstrates how to query from Hygraph with GenQL.                                                                                                                                                                                                              |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-golang" target="_blank">Go Lang</Link>                                            | This example demonstrates how to query from Hygraph with Go.                                                                                                                                                                                                                 |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-graphcms-image" target="_blank">graphcms-image</Link>                             | This example demonstrates how to use @graphcms/react-image with Gatsby.                                                                                                                                                                                                      |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-graphql-codegen" target="_blank">GraphQL Codegen</Link>                           | This example demonstrates how to query from Hygraph with Apollo Client 3, TypeScript, and generated types for your Hygraph project with GraphQL Code Generator.                                                                                                              |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-graphql-mesh" target="_blank">graphql-mesh</Link>                                 | This example demonstrates how to use GraphQL mesh to serve 3 separate APIs, Hygraph, CartQL, and SpaceXLand.                                                                                                                                                                 |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-gridsome" target="_blank">Gridsome</Link>                                         | This example demonstrates how to query data from Hygraph with `@gridsome/source-graphql`.                                                                                                                                                                                    |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-houdini" target="_blank">Houdini</Link>                                           | This example shows how to use the SvelteKit GraphQL library Houdini with Hygraph.                                                                                                                                                                                            |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-kitql" target="_blank">KitQL</Link>                                               | This example shows how to use the KitQL with Hygraph.                                                                                                                                                                                                                        |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-management-sdk" target="_blank">Management SDK</Link>                            | This example demonstrates how to programmatically build a project schema using the Hygraph Management SDK.                                                                                                                                                                   |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-mutations" target="_blank">Mutations</Link>                                      | This example demonstrates how to mutate Hygraph data with `Next.js.`                                                                                                                                                                                                         |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextauth-credentials" target="_blank">Next Auth</Link>                            | This example demonstrates how to query from Hygraph `NextAuth.js`.                                                                                                                                                                                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-app-directory" target="_blank">Next App Router</Link>                      | This example demonstrates how to query from Hygraph with `graphql-request` in `Next.js`.                                                                                                                                                                                     |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-i18n-routing" target="_blank">Next i18n Routing</Link>                     | This example demonstrates how to use `Next.js` Internationalized Routing with localized Hygraph content.                                                                                                                                                                     |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-image" target="_blank">Next Image</Link>                                   | This example demonstrates how to use the `Next.js` Image Component with your Hygraph assets.                                                                                                                                                                                 |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-image-loader" target="_blank">Next Image Loader</Link>                     | This example demonstrates how to use a custom loader function with `Next.js` Image Component and Hygraph assets. This allows you to perform asset transformations using the Hygraph CDN, rather than the default `Next.js` loader.                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-mdx-remote" target="_blank">Next mdx remote</Link>                         | This example demonstrates how to use markdown fields from Hygraph with `MDX` in `Next.js`.                                                                                                                                                                                   |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs" target="_blank">NextJs</Link>                                             | This example demonstrates how to query from Hygraph with `graphql-request` in `Next.js`.                                                                                                                                                                                     |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nuxtjs" target="_blank">NuxtJs</Link>                                             | This example demonstrates how to query from Hygraph with `Nuxt.js`.                                                                                                                                                                                                          |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nuxtjs-graphql" target="_blank">NuxtJs GraphQL</Link>                             | Hygraph, `NuxtJS` & `nuxt-graphql-client`.                                                                                                                                                                                                                                   |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-pagination" target="_blank">Pagination</Link>                                    | This example demonstrates ways you can paginate Hygraph queries.                                                                                                                                                                                                             |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-remote-fields" target="_blank">Remote Fields</Link>                              | This example demonstrates how to programmatically build a project schema using the Hygraph Management SDK. Using Remote Fields, we create a PricingPlan model to query for product/price data directly from the Stripe API.                                                  |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-react-query" target="_blank">React query</Link>                                   | This example demonstrates how to query from Hygraph with React Query in `React.js`.                                                                                                                                                                                          |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-reactjs" target="_blank">ReactJs</Link>                                           | This example demonstrates how to query from Hygraph with `graphql-request` in `React.js`.                                                                                                                                                                                    |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-rich-text-react-renderer" target="_blank">Rich Text renderer</Link>              | This example demonstrates how you can render Rich Text from Hygraph.                                                                                                                                                                                                         |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-slinkity" target="_blank">Slinkity</Link>                                         | This example shows how to use the Slinkity and GraphQL Request with Hygraph.                                                                                                                                                                                                 |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-sveltekit" target="_blank">SvelteKit</Link>                                       | This example shows how to use the SvelteKit with Hygraph. It uses `graphql-request`.                                                                                                                                                                                         |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-sveltekit-and-graphql-request" target="_blank">SvelteKit & GraphQL Request</Link> | This example shows how to use the SvelteKit and GraphQL Request with Hygraph.                                                                                                                                                                                                |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-sveltekit-and-urql" target="_blank">SvelteKit & URQL</Link>                       | This example shows how to use the SvelteKit with Hygraph and URQL.                                                                                                                                                                                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-swift" target="_blank">Swift</Link>                                               | This demonstrates how to use Hygraph with a Swift application for iOS (iPhone / iPad) or Mac.                                                                                                                                                                                |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-swift-graphql" target="_blank">Swift & swift-graphql</Link>                       | This demonstrates how to use Hygraph with a Swift application for iOS (iPhone / iPad) or Mac, using popular library `swift-graphql`.                                                                                                                                         |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-swr" target="_blank">Swr</Link>                                                   | This example uses SWR to fetch, and mutate user todos using Next.js API Routes, backed by GraphQL.                                                                                                                                                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-terraform" target="_blank">Terraform</Link>                                       | Terraform example.                                                                                                                                                                                                                                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-union-types" target="_blank">Union types</Link>                                  | Hygraph supports polymorphic relations, also known as GraphQL union types. This example demonstrates how you can build a product marketing page using a schema consisting of polymorphic relations. The example is built with `Next.js`, `graphql-request` and Tailwind CSS. |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-upload-proxy" target="_blank">Upload Proxy</Link>                                 | This example demonstrates how to proxy uploads from your client application to Hygraph to prevent leaking the Permanent Auth Token needed to upload new assets.                                                                                                              |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-urql-core" target="_blank">URQL core</Link>                                       | This example demonstrates how to query from Hygraph with core URQL client.                                                                                                                                                                                                   |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-urql-react" target="_blank">URQL React</Link>                                     | This example demonstrates how to query from Hygraph with React URQL client.                                                                                                                                                                                                  |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-where-filter" target="_blank">Using where filter</Link>                          | This example demonstrates ways you can order Hygraph query results by using variables. The example is built with `Next.js`, `graphql-request` and swr.                                                                                                                       |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-vanilla-javascript" target="_blank">Vanilla JS</Link>                             | This example demonstrates how to query data from Hygraph in the browser with just JavaScript.                                                                                                                                                                                |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/using-order-by-filter" target="_blank">Variables</Link>                                | This example demonstrates ways you can order Hygraph query results by using variables. This example is built with `Next.js`, `graphql-request` and swr.                                                                                                                      |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-vuejs" target="_blank">VueJs</Link>                                               | This example demonstrates how to query from Hygraph with `Vue.js.`                                                                                                                                                                                                           |


---
# Working with Hygraph

Source: https://hygraph.com/docs/developer-guides/index

Hygraph is the Headless CMS allowing you to build digital experiences the way you envisioned them - with all your backends, frontends, and services, working together in harmony.

Hygraph gives you instant GraphQL Content APIs to create, enrich, unify, and deliver your content across platforms.

<VideoEmbed videoId="s-47dgkrQns" />

## Getting started flow

You can get started with Hygraph by following the **Getting Started flow** which will walk you through:

- [Planning your content flow](/docs/getting-started/plan-content-flow/)
- [Designing your content models](/docs/getting-started/design-content-models/)
- [Building your content models](/docs/getting-started/build-content-models/)
- [Configuring reference fields](/docs/getting-started/configure-reference-fields/)
- [Configuring enumerations](/docs/getting-started/configure-enumerations/)
- [Building components](/docs/getting-started/build-components/)
- [Adding components to your models](/docs/getting-started/add-components-to-models/)
- [Adding a Remote Source](/docs/getting-started/add-remote-source/)
- [Adding Remote Fields](/docs/getting-started/remote-fields/)
- [Adding Top-level Remote Fields](/docs/getting-started/top-level-remote-fields/)
- [Creating content](/docs/getting-started/content-creation/)
- [Localizing content](/docs/getting-started/content-localization/)
- [Additional content features](/docs/getting-started/additional-content-features/)
- [Queries](/docs/getting-started/api-playground-queries/)
- [Mutations](/docs/getting-started/api-playground-mutations/)
- [Connecting your frontend using Next](/docs/getting-started/frontend-creation/)
- [Connecting your storefront](/docs/getting-started/connect-storefront/)
- [Setting up a preview URL](/docs/getting-started/preview-url-creation/)
- [Using webhooks](/docs/getting-started/configure-webhooks/)

## Content modeling

At the core of every project is the schema. It's important your schema is carefully structured, and designed modelled around the content you will be storing.

We've got a guide on the basics of content modeling, and how Hygraph gives you all the tools to structure your content.

[Learn more about content modeling](/docs/getting-started/fundamentals/content-modeling)

## Going beyond the basics

Once you've completed our [getting started tutorial](/docs/getting-started/onboarding-overview), you will want to explore our growing list of code examples, tutorials, and more.

- [API Reference](/docs/api-reference)
- <Link href="https://github.com/hygraph/hygraph-examples" target="_blank">Code Examples</Link>
- [Tutorials](/blog/tag/build-with-hygraph)

## What is a headless CMS?

If you're new to the concept of Headless CMS then you should read our <Link href="https://hygraph.com/headless-cms#what-is-a-headless-cms" target="_blank">blog article</Link>. It'll take less than 5 minutes.

## Section contents

This section offers a contents map to help you readily find what you're looking for.

### Project guides

| Document                                                                              | Contents                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Project information](/docs/developer-guides/project/manage-project-info)             | Contains information about managing your project's global information. In this document you will find information about your project details, how to clone a project, share it, manage support access, leave a project, or delete it.                    |
| [Environments](/docs/developer-guides/project/manage-project-environments)            | Contains information about managing your project's environments. In this document you will find information about creating, switching and deleting environments, as well as promoting an environment to master.                                        |
| [Multiple environments](/docs/developer-guides/project/multiple-environments)         | Contains information about working with multiple environments, such as the reasons to do this, setting up a development environment, maintaining changes that happened while in development, and promoting an environment to master.                   |
| [Roles and permissions](/docs/developer-guides/project/roles-and-permissions)         | Contains information about managing the roles and permissions of your project. In this document you will find information about system and custom roles, adding and removing users to roles, and examples on different setups for your project.        |
| [Audit logs](/docs/developer-guides/project/audit-logs)                               | Contains information about working with audit logs, which allow you to see all changes inside your project. In this document you will find information about accessing audit logs, event fields, logged resources, logged actions, and filtering logs. |
| [Configuring content stages](/docs/developer-guides/project/configure-content-stages) | Learn about how system content stages work, and how to configure custom ones.                                                                                                                                                                          |
| [Update your password](/docs/developer-guides/project/update-your-password)           | Contains information about how to update your password.                                                                                                                                                                                                |
| [Update billing](/docs/developer-guides/project/update-billing)                       | Contains information about how to update your billing information.                                                                                                                                                                                     |
| [Clone your project](/docs/developer-guides/project/clone-your-project)               | Contains information about how to clone your project. In this document you will also find some additional information on cloning limitations.                                                                                                          |
| [Share your project](/docs/developer-guides/project/share-your-project)               | Contains information about how to share your existing project's master environment as a template with others.                                                                                                                                          |
| [Locales](/docs/developer-guides/project/manage-project-locales)                      | Contains information about managing your project's locales.                                                                                                                                                                                            |
| [Team members](/docs/developer-guides/project/manage-team-members)                    | Contains information about managing team members in a project.                                                                                                                                                                                         |
| [Collaborator view](/docs/developer-guides/project/collaborator-view)                 | Contains information about our Collaborator view feature, which shows you in real time all users who are viewing an entry.                                                                                                                             |
| [Content workflows](/docs/developer-guides/project/content-workflows)                 | Contains information about our Content Workflows feature, which help teams manage content creation and approval in a clear and structured way.                                                                                                                            |
| [Commenting](/docs/developer-guides/project/commenting)                               | Contains information about our commenting feature. In this document you will find information about notifications and comments.                                                                                                                        |

### Schema guides

| Document                                                                           | Contents                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Command menu](/docs/developer-guides/schema/command-menu)                         | Contains information about using the command menu feature for keyboard navigation.                                                                                                                                                                                                                                                                                                            |
| [Components](/docs/developer-guides/schema/components)                             | Contains information about components, which are a predefined set of fields that can be reused across models and content entries. In this document you will find information on how to create and add components to a field, how to use components in content entries, how to query components, how to create and use nested components, and how to decide between components and relations. |
| [References](/docs/developer-guides/schema/references)                             | Contains information about the configuration of reference fields, and the different types available.                                                                                                                                                                                                                                                                                          |
| [Components or references](/docs/developer-guides/schema/components-or-references) | Contains information that can help you decide whether to use a component or a reference in your project schema.                                                                                                                                                                                                                                                                               |
| [Enumerations](/docs/developer-guides/schema/using-enumerations)                   | Contains information about working with enumerations, which can be used to group values within a type. In this document you will find information on creating, adding, deleting, and using enumerations.                                                                                                                                                                                      |
| [Taxonomies](/docs/developer-guides/schema/taxonomies)                   | Contains information about working with taxonomies, which can be used to define hierarchical structures for content classification. In this document you will find information on creating, adding, deleting, and using taxonomies.                                                                                                                                                                                      |
| [Live preview](/docs/developer-guides/schema/live-preview)                         | Contains information about working with the live preview feature to preview content in your frontend before it's published.                                                                                                                                                                                                                                                                   |
| [Remote sources](/docs/developer-guides/remote-data/remote-sources)                | Contains information about Remote Sources, which is our content federation utility. With Remote sources, it's possible to add content from other systems and sources to the Hygraph API without having to migrate the content itself.                                                                                                                                                         |
| [Remote content & data](/docs/developer-guides/remote-data/remote-content)         | Contains information about using remote fields to fetch external data. Use this document to learn about remote fields in the context of a regular model, and top level remote fields, which fetch data unrelated to Hygraph.                                                                                                                                                                  |
| [Reserved terms](/docs/developer-guides/schema/reserved-terms)                     | Contains a list of reserved terms. Attempting to use these terms will result in a warning, informing you that you must use a different word instead.                                                                                                                                                                                                                                          |
| [Slug field](/docs/developer-guides/schema/slug-field)                             | Contains information about working with the slug field. In this document you will find information on how to configure the slug field to be generated from other field values in your model.                                                                                                                                                                                                  |
| [Conditional fields](/docs/developer-guides/schema/conditional-fields)             | Contains information about working with conditional fields. In this document you will find information on how to configure conditional visibility for the fields in your schema.                                                                                                                                                                                                              |

### Content guides

| Document                                                                      | Contents                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Accessing content](/docs/developer-guides/content/access-created-content)    | Contains information about accessing created content.                                                                                                                                                                               |
| [Configuring columns](/docs/developer-guides/content/configuring-columns)     | Contains information about configuring columns in order to declutter your content views by hiding information that is not relevant to you.                                                                                          |
| [Searching for content](/docs/developer-guides/content/searching-for-content) | Contains information about using the search feature in our content.                                                                                                                                                                 |
| [Using filters](/docs/developer-guides/content/using-filters)                 | Contains information about using filters in order to restrict the content shown by specific parameters.                                                                                                                             |
| [Content views](/docs/developer-guides/content/content-views)                 | Contains information about default and custom content views. In this document you will find information on how to update default views, how to create/edit/delete/organise custom views, and how to create/edit/delete view groups. |
| [Creating content](/docs/developer-guides/content/creating-content)           | Contains information about creating content as well as connecting related content.                                                                                                                                                  |
| [Updating content](/docs/developer-guides/content/updating-content)           | Contains information about updating content as well as sorting related content.                                                                                                                                                     |
| [Deleting content](/docs/developer-guides/content/deleting-content)           | Contains information about deleting content as well as removing related content.                                                                                                                                                    |
| [Duplicating content](/docs/developer-guides/content/duplicating-content)     | Contains information about duplicating content and relations.                                                                                                                                                                       |
| [Publishing content](/docs/developer-guides/content/publishing-content)       | Contains information about publishing content. You will also find information on outdated content and on editing published content.                                                                                                 |
| [Content stages](/docs/developer-guides/content/content-stages)               | Contains information about Hygraph's default content stages and about creating custom workflows using content stages.                                                                                                               |
| [Versioning content](/docs/developer-guides/content/versioning-content)       | Contains information about versioning content, which allows you to view the evolution of the project's published content.                                                                                                           |
| [Content localization](/docs/developer-guides/content/content-localization)   | Contains information about content localization, which is supported as a core feature in Hygraph. In this document you will find information on adding translations and showing/hiding fields.                                      |
| [Scheduled publishing](/docs/developer-guides/content/scheduled-publishing)   | Contains information about scheduling content to be published or unpublished. In this document you will find information on how to schedule items or releases, how to create a release, and scheduling limitations.                 |
| [Customize sidebar](/docs/developer-guides/content/customize-sidebar)         | Contains information about customizing your sidebar by adding, removing or reordering widgets.                                                                                                                                      |
| [Rich Text editor](/docs/developer-guides/content/rich-text-editor)           | Contains information about Hygraph's Rich Text editor, which provides great flexibility when it comes to creating, editing, and manipulating content entries showcasing text and images.                                            |

### Asset guides

| Document                                                 | Contents                                                                                     |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Add asset entry](/docs/developer-guides/assets/add-asset-entry)   | Contains information about adding asset entries, which allows adding metadata to your asset. |
| [Upload asset](/docs/developer-guides/assets/upload-asset)         | Contains step by step information about the asset upload process.                            |
| [Work with assets](/docs/developer-guides/assets/work-with-assets) | Contains information about working with assets.                                              |

### Webhooks

| Document                                                                  | Contents                                                                                                                                           |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Overview](/docs/developer-guides/webhooks/webhooks-overview)                       | Contains general information about the use of webhooks with Hygraph, such as configuring webhooks, viewing logs, and editing or deleting webhooks. |
| [Deploy your Vercel project](/docs/developer-guides/webhooks/trigger-static-build)  | Contains all the necessary information to deploy your Vercel project using webhooks.                                                               |
| [Deploy your Gatsby project](/docs/developer-guides/webhooks/deploy-gatsby-project) | Contains all the necessary information to deploy your Gatsby project using webhooks.                                                               |

&nbsp;

&nbsp;


---
# Audit logs

Source: https://hygraph.com/docs/developer-guides/project/audit-logs

Audit Logs allow you to see all changes inside of your project. They contain both changes in the schema and content.

<Alert theme="info">

Audit Logs are an Enterprise pricing feature.

</Alert>

Whenever a member of your project creates a new model, updates a content entry, or deletes a webhook, the Audit Logs will retain these actions.

![Audit Logs Explorer](/images/docs/user-guides/audit-logs-view.png)

## Accessing audit logs

On eligible projects, Audit Logs are visible for the Owner & Admin role. You can also grant access to Audit Logs by creating a custom role with the "Can view Audit Logs" permission.

Clicking on a specific row in the Audit Logs table opens the detail view for that event, including the payload that shows all changes that happened on this event.

![Audit Logs Details View](/images/docs/user-guides/audit-logs-detail.png)

If you need to fetch the most recent updates once you are already examining logs, use the refresh button at the top-right of the screen.

![Reload audit logs](/images/docs/user-guides/audit-logs-reload.png)

## Event fields

Each audit event will have the following fields present:

| Field                | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| Entity ID            | The ID of the Resource, e.g. Model ID or Content Entry ID.                       |
| Timestamp            | The time at which the change occurred.                                           |
| Type (Resource Type) | The type of resource that has been altered.                                      |
| Action               | The action that was performed on the resource.                                   |
| Environment          | The environment in which the change occurred.                                    |
| Payload              | The full payload of the change. We won't include the payload for content changes. |
| TriggeredBy          | The Member email or Token that triggered the change.                             |
| TriggerType          | Can be `USER`, `PAT`, `OPEN` or `THIRD_PARTY`.                                   |

## Logged resources

Here's a list of resource types the Audit Logs will keep track of:

- Model
- Environment
- Field
- Content
- Webhook
- Locale
- Project
- Stage
- Member
- Role
- View Group
- Content View
- PAT (Permanent Access Token)
- Enumeration

## Logged actions

These are the actions that can be performed on resources:

- Accept (users)
- Create
- Update
- Delete
- Publish (content only)
- Unpublish (content only)

## Filtering logs

You can filter the logs by the [event fields](#event-fields).

![Filtering logs](/images/docs/user-guides/audit-logs-filter.png)

### Filter by action

To filter by action, select `Action` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-action.png)

Select one of the actions from the dropdown menu to filter the results on the table.

### Filter by entity ID

To filter by entity ID, select `Entity ID` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-entityid.png)

Enter a resource entity ID in the input field to filter the results on the table.

### Filter by environment

To filter by environment, select `Environment` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-env.png)

Enter the name of one of your environments in the input field to filter the results on the table.

Global actions such as inviting a member to your project count for all environments and do not display with this filter.

### Filter by timestamp

To filter by timestamp, select `Timestamp` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-timestamp.png)

Select a condition from the dropdown and then enter a timestamp value in UTC format in the input field to filter the results on the table.

### Filter by user

If you want to search for the audit logs of a specific team member, select `Triggered by` from the `Filter`:

![Search for logs of a team member](/images/docs/user-guides/audit-logs-member.png)

Leave the trigger type as `User` and write their email in the `Triggered by` input field.

The table will be ordered descending by default, so the newest entry is shown first.

### Filter by trigger type

To filter by trigger type, select `Trigger type` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-triggertype.png)

Select a trigger type from the dropdown menu to filter the results on the table.

- **App Token:** Actions triggered by an application token used for API authentication or automated processes.
- **Open:** Requests sent to a public content API, without any auth tokens. **We do not recommend enabling permissions to mutate content in these cases**. We suggest that you use a PAT instead.
- **PAT:** Actions performed using a Permanent Auth Token (PAT) for API access.
- **Third Party:** Events initiated by external integrations or connected third-party applications.
- **User:** Actions directly performed by a logged-in user in the Hygraph UI.

### Filter by type

To filter by type, select `Type` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-type.png)

Select a type from the dropdown menu to filter the results on the table.

### Filter by user email

To filter by user email, select `User email` from the `Filter` menu:

![Filter by action](/images/docs/user-guides/audit-logs-filter-email.png)

Enter an email in the input field to filter the results on the table.

---
# Backup & recovery

Source: https://hygraph.com/docs/developer-guides/project/backup-and-recovery

## Overview

<Alert theme="warning">

**This feature is an addon for enterprise customers. [Contact sales to learn more](/contact)**

</Alert>

In the case of unintentional deletions, Backup & Recovery allows project admins to roll back their main environment to a previous working version within seconds.

## What you can do

- Automatic daily backup of a project's `master` environment, with up to a 7-day retention period.
- Easy recovery for project admins in case of accidental deletions.
- Recovery within seconds to a previous backup as a new environment that you can promote.
- Backups contain content, assets & schema.

## Backup creation

When the feature is enabled, backups are created automatically every day, during non-working hours, and kept for up to 7 days.

Project admins can see the next scheduled backup date & time, and the general retention. We also show the list of all available backups:

![Clone settings](/images/docs/user-guides/project-guides/backups-list.png)

## Recover backup

Click `Recover backup` on one of the backup cards to start the process:

![Recover backup](/images/docs/user-guides/project-guides/backups-recover.png)

A modal with two selection options will display:

### Recover backup only

![Recover backup only](/images/docs/user-guides/project-guides/recover-backup-only.png)

The `Recover backup only` option creates a new environment from the backups.

### Recover backup & promote to master

The `Recover backup & promote to master` option turns the backup into a normal environment and promotes that to master.

The backup replaces the old master environment.

![Recover backup & promote to master](/images/docs/user-guides/project-guides/recover-backup-and-promote.png)

If you select this option, you must also choose a name for the demoted master environment, [like in our normal promotion flow](/docs/developer-guides/project/manage-project-environments#promote-environments-to-master). 

This process will only take a few seconds.

#### Asset URLs change

Since backups are created as a new environment, the asset URLs will be different. Make sure to check for asset URLs stored in other places, such as source code or external systems.

Please note that, while in the past every single handle would have been updated, with the new asset system only the base URL changes on cloned environments.

<Alert theme="warning" title="Old URL change behavior">

Original asset URL:

`https://media.graphassets.com/6gB5FZ9mQiWHOu6Lt95p`

Asset URL after backup:

`https://media.graphassets.com/<random new handle>`

</Alert>

With the new **Hygraph Asset Management System**, the following asset URL:

```
https://eu-west-2.graphassets.com/cm1q9b9c401cv07ut4wcgf2uj/cm2kmqsf6002a07ukg3z7sjzg
```

Would turn into something like this:

```
https://eu-west-2.graphassets.com/<new asset env id>/cm2kmqsf6002a07ukg3z7sjzg
```

Since the asset ID remains the same, you can simply run a search for the old asset environment ID and replace it with the new one.



---
# Clone your project

Source: https://hygraph.com/docs/developer-guides/project/clone-your-project

You can clone your existing project's master environment. Cloning copies your entire project: its schema, content, and settings. If you only need specific schema elements from another project rather than a full copy, [import schema elements](/docs/developer-guides/schema/import-schema) instead.

Inside your project settings you can click on `Clone project`.

![Project settings](/images/docs/user-guides/project-settings-clone.png)

Give your project a name, optional description, and select the region where its data will be stored, whether you want to clone existing content, assets, and/or configured webhooks.

![Clone settings](/images/docs/user-guides/clone-settings.png)

## Cloning limitations

### Cloning in progress

If one of your projects is in the process of being cloned, you will not be able to start another clone until the previous process is finished. Attempting to do so will prompt a warning message indicating this at the top of the screen.

![Cloning limitation warning message](/images/docs/user-guides/cloning-limitation-warning.png)

<Alert theme="info">
Users can process one cloning operation at a time, irrespective of the project.

Even if a clone has been scheduled, users can continue issuing other schema changes - except cloning - in their projects and environments.

These limitations also affect public cloning.
</Alert>

### Clone project access

Only project **Owners** can access the cloning controls and links.

Users other than the project owner cannot see the **Clone project** screen section in `Project Settings > General > Project`.

### Apps

When you clone an environment, the apps installed in it are cloned too. However, cloning creates apps in **"incomplete setup"** for security reasons.

You will need to complete your app configuration by manually adding passwords, or API Keys.

After completing setup, the app will work as it did in the previous environment.

## Public cloning

If public cloning is enabled under [Share your project](/docs/developer-guides/project/share-your-project) in `Project settings > General > Project`, you get a link that you can share.

![Project settings - Public cloning](/images/docs/user-guides/project-settings-share.png)

Using this link, other users will be able to clone your project into their own accounts. This is the screen they will see when using the public cloning link:

![Project settings - Public cloning](/images/docs/user-guides/public-cloning-screen.png)

From here on, they can follow the [Create a project](/docs/getting-started/fundamentals/quickstart#create-a-project) flow.

<Alert theme="info" title="Pro Tip">
You can use this to create your own starter project and share it with other people.
</Alert>

## Create your own starter

If your work involves using a large number of very similar projects, public cloning might help you work more efficiently.

In the following video, Bryan urges you to **work smarter not harder** by creating a project to use as a starter, then using cloning to create copies of it, which you can then work on:

<VideoEmbed videoId="HXI7EysvFMk" />


---
# Collaborator view

Source: https://hygraph.com/docs/developer-guides/project/collaborator-view

Our Collaborator view feature helps editors avoid accidentally overwriting and losing content that someone else is currently working on.

The feature shows you exactly who's interacting with a content entry at the same time as you.

## How it works

You will see your own avatar at the top-right corner of the screen as soon as you open a content entry:

![Collaborator view - User's name on hover](/images/docs/user-guides/collaborator-view/collaborator-view-hover-text-you.png)

If someone else opens that content entry, you will see their avatar next to yours. You can hover over an avatar to see the name of the user:

![Collaborator view - User's name on hover](/images/docs/user-guides/collaborator-view/collaborator-view-hover-text.png)

If more than 3 users are looking at the content entry, the screen will only display two, plus a counter that shows how many more are viewing it.

On hover, the counter will display a card showing the avatars and names of all users currently viewing the content entry:

![Collaborator view - User's name on hover](/images/docs/user-guides/collaborator-view/collaborator-view-hovercard.png)


---
# Commenting

Source: https://hygraph.com/docs/developer-guides/project/commenting

Commenting is a functionality designed with larger teams containing multiple content editors in mind, to promote work collaboration. You will be able to leave comments in content entries, as well as receive notifications related to the comments.

## Notifications

The **Notifications** menu is located in the sidebar of your **Hygraph** project, by the bell icon. If you have any unread notifications, a red alert will display next to it.

<VideoEmbed videoId="jKk07QdpQrA" />

You will be notified whenever you are mentioned in a comment, and when a comment that you have either authored or have been mentioned in is resolved or re-opened.

To access these notifications, simply click on the **Notifications** menu. For each one, you have the following options:

- `Mark as read` or `Mark as unread` depending on the notification status.
- Click on the notification to access the related comment.
- `Mark all as read` by clicking on the button at the top-right corner of the notifications screen.
- Filter notifications by `All` or `Unread`, by clicking the filter icon at the top of the screen.
- Use the configuration menu at the top of the screen to select how you want to receive notifications: in the app, via email, none, or both.

<Alert theme="warning">

Please note that notifications displayed here are from all your projects, not just the project you're currently in.

</Alert>

## Comments

<VideoEmbed videoId="ilOHGJ4xs6o" />

You can find the comments on the sidebar of a content entry, by clicking on the Comments button at the top.

![Comments](/images/docs/editor-guides/collaboration/comments-sidebar.png)

At the top, the sidebar displays how many comments there are in the current content entry, along with a status filter to help you quickly find what you're looking for.

![Comments number & status filter](/images/docs/editor-guides/collaboration/comments-number-status-filter.png)

<Alert theme="info" title="Pro Tip">

When you click on a notification, it will take you to the corresponding content entry, where the comment you were notified about will be highlighted.

</Alert>

In the **Comments** sidebar, you can:

- **Leave a new comment:** Write your comment in the text box located at the top of the **Comments** sidebar and click `Add`. You can mention people as well as project roles in your comment by using `@`, which will display a list of users and roles for you to select from. Mentioning people or roles may cause an alert to pop up in their [notifications](/docs/developer-guides/project/commenting#notifications), and/or receive an email depending on their notifications configuration.
  - **Assign a comment:** When you're writing a new comment, you can click `Assign` to assign it to a team member in the project. Upon clicking, a list of users will display and you can simply select one with a click.
- **Use the status filter:** This dropdown menu allows you to sort comments by `All`, `Assigned`,`Open`, and `Resolved`.
- **Reply to a comment:** If you want to reply to a specific comment, you can click **Reply** under it. Once saved, the comment will display as nested within the parent comment. You can click `Reply` to show it, or `Hide` to hide it.
- **Use the context menu:** Use this menu to access the following actions.
  - **Edit:** Clicking on this option allows you to edit the contents of a comment, then click `Update` to save it. You can only edit your own comments while they are open. This option only displays for your own comments.
  - **Resolve / Re-open:** Clicking on this option marks the comment as resolved / re-opened. The people mentioned in the comment will be [notified](/docs/developer-guides/project/commenting#notifications).
  - **Un-assign:** Clicking on this option un-assigns a comment.
  - **Copy link**: Clicking on this option copies the link to the comment. When used, that link will lead to the comment, which will be highlighted in order to be easily found.
  - **Delete:** Clicking on this option deletes the comment. This option only displays for your own comments.

<Alert theme="warning">

The <b>Comments</b> sidebar will only appear in a content entry once it has already been saved for the first time. Before the first save, only the <b>Info</b> sidebar will be available.

</Alert>

## Commenting & notifications workflow

The following diagram shows a simplified workflow including 2 users collaborating through our commenting feature:

![Hygraph commenting & notifications workflow](/images/docs/user-guides/workflow-commenting.png)


---
# Configuring content stages

Source: https://hygraph.com/docs/developer-guides/project/configure-content-stages

## Overview

Hygraph offers two OOTB system content stages, plus the ability to [create custom content stages](/docs/developer-guides/project/configure-content-stages#creating-custom-content-stages) depending on your plan.

This document provides information on how system content stages work, and how to work with custom stages.

<Alert theme="info" title="Are you looking for our API Reference?">
[Check out our API Reference document on content stages](/docs/api-reference/content-api/content-stages)
</Alert>

## What you can do

You can use the [system content stages](/docs/developer-guides/project/configure-content-stages#system-content-stages) OOTB, or customize your workflow by creating [custom content stages](/docs/developer-guides/project/configure-content-stages#custom-content-stages).

## System content stages

Hygraph has two system content stages, `DRAFT` and `PUBLISHED`. These content stages cannot be edited or deleted.

`DRAFT` allows people to add and edit content without affecting published content. Promoting the content to the `PUBLISHED` stage, pushes it live, which means it can be consumed by others.

<Alert theme="info" title="Pro Tip">
Click [here](/docs/developer-guides/content/content-stages) learn more about how system content stages work.
</Alert>

## Custom content stages

### Creating custom content stages

To create your own content stages, navigate to **Project settings > General > Content stages**.

The default screen shows the `DRAFT` and `PUBLISHED` system stages, and offers the option to upgrade your plan if you want to configure any additional stages.

![Content Stages Project Settings](/images/docs/user-guides/content-stages-settings.png)

The `QA` stage card is grayed out as it's not part of the **Community Plan**. Clicking on the `Upgrade to add this content stage` link at the bottom of this card displays a popup where you can select the best plan for your project.

![QA Stage](/images/docs/user-guides/content-stages-qa.png)

You can also change the order of your destination content stages by clicking on the six dots handle, located to the left of each configured stage card, and dragging.

If you haven't reached the limit of stages for your plan, then you will simply be provided with the option of adding a new stage.

![+ Add stage](/images/docs/user-guides/content-stages-add.png)

If your project allows custom content stages, clicking on `+ Add stage` displays a screen that requires you to provide a `Display name` and select a label color. You can optionally add a description. The `API ID` field will be autocompleted as you write the display name.

![+ Add stage](/images/docs/user-guides/content-stages-create.png)

After typing in all the necessary information, you can click `Add` to create the content stage.

<Alert theme="info">
Creating custom content stages is available to paid plans. <Link href="https://hygraph.com/pricing" target="_blank">Upgrade your plan</Link>.
</Alert>

### Editing custom content stages

To edit a custom content stage, navigate to **Project settings > General > Content stages** in your Hygraph project, and click on the `Edit` button on the card of the content stage you want to edit.

![Edit stage](/images/docs/user-guides/content-stages-edit.png)

The content stage details page will display. Edit the information you need to change, then click `Update` to save your changes.

![Edit stage - details screen](/images/docs/user-guides/content-stages-edit-details.png)

### Deleting custom content stages

To delete a custom content stage, navigate to **Project settings > General > Content stages** in your Hygraph project, and click `Delete` on the card of the content stage you want to delete.

![Delete stage](/images/docs/user-guides/content-stages-delete.png)

A confirmation screen displays, where you need to type in the stage name, then click `Delete stage` to proceed.

![Delete stage - confirmation screen](/images/docs/user-guides/content-stages-delete-confirmation.png)


---
# Content Freeze

Source: https://hygraph.com/docs/developer-guides/project/content-freeze

If you change a field or model while an editor is mid-save, their entry can conflict with the new schema, or publish in a state you didn't intend. Editors can also lose work if you promote schema changes between environments while they're still working. Content Freeze pauses content and asset creation, editing, and publishing so you can promote schema safely.

## Availability

- **Permission**: Only users with the **Allows starting, scheduling, and lifting content freezes** permission can trigger, manage, or lift a freeze. The Admin role includes this permission by default.
- **Plan**: Available on every plan.

<Alert theme="warning">
Content Freeze only blocks Save and Publish actions in Studio. It does not enforce anything at the Content API level. Scripts, integrations, or direct API calls can still read and write content while a freeze is active.
</Alert>

## Configure a freeze

1. Navigate to **Project Settings > Governance > Content Freeze**.
2. Under **Start or schedule a freeze**, choose a **Scope**: **Specific environments** or **Entire project (includes future environments)**.
3. If you chose **Specific environments**, select one or more from the **Environments** dropdown.
4. Set **Start**: **Now** or **At a scheduled time**.
5. Set **End**: **Until I lift it** or **At a scheduled time**.
6. (Optional) Add a **Message**. This message is shown to all users while the freeze is active.
7. Click **Apply freeze**.

![Content Freeze configuration form](/images/docs/developer-guides/project-guides/content-freeze.png)

Freezes you create appear under **Active & scheduled**, listing the scope, the time window, and who set it.

![Content Freeze active & scheduled list](/images/docs/developer-guides/project-guides/content-freeze-active-scheduled.png)

While a freeze is active or scheduled in their environment, all users see a banner on every page in Studio. Once the freeze is **active**, users can't add new entries or assets, or click **Save** or **Publish** on content entries or assets. A scheduled freeze shows the banner before it starts, but editing remains available until the start time. Reading and browsing content still works through a freeze.

## Lift a freeze early

1. Go to **Project Settings > Governance > Content Freeze**, or click **Manage freeze** in the Studio banner.
2. Find the freeze under **Active & scheduled**.
3. Click the unlock icon in that row to lift it.

![Content Freeze lift form](/images/docs/developer-guides/project-guides/content-freeze-lift.png)

Users regain the ability to save and publish as soon as you lift the freeze.

## Review past freezes

Completed freezes, whether lifted early or ended on schedule, appear under **Recent freezes** on the same page. Each row shows the scope, the time window, who set the freeze, and who lifted it.

![Content Freeze recent freezes list](/images/docs/developer-guides/project-guides/content-freeze-recent-logs.png)

## Related docs

- [Content Freeze API reference](/docs/api-reference/basics/content-freeze): `setContentFreeze` and `liftContentFreeze` mutations, and the `contentFreezes` query.
- [Promote environments](/docs/api-reference/basics/environments#promoting-environments): Move schema changes between environments.


---
# Content workflows

Source: https://hygraph.com/docs/developer-guides/project/content-workflows

## Overview

**Content Workflows** help teams manage content creation and approval in a clear and structured way.

### Why content workflows matter

Publishing content often involves multiple steps, like reviews, QA, translations, and asset creation. Without a workflow, teams face challenges such as:

- **Content consistency:** Changes can be made after review, leading to mistakes.
- **Transparency:** It's hard to track content status and know who needs to take action.
- **Workflow enforcement:** Content might get published before it's fully approved.

Hygraph Content Workflows solve these problems by creating a structured, step-by-step process. This ensures teams follow a clear path from draft to publication.

### Key features & benefits of workflows

Hygraph Workflows help teams manage content efficiently by providing:

- **Structured workflows:** Admins can set up step-by-step workflows with clear stages.
- **Granular permissions:** Each step can have assigned roles, ensuring only the right people can edit or approve content.
- **Automated publishing:** Content can move to the next stage or be published automatically after approval.
- **Better visibility and tracking:** Editors can filter and track content based on its workflow stage.
- **Stronger compliance and control:** Prevents unauthorized changes and keeps content versions consistent.

## Create a workflow

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xawwhu9307vxp4tinngw" caption="Create a workflow" />

1. Navigate to `Project Settings > Governance > Workflows`.
2. Click `+ Add Workflow` to create a new one.
3. Provide a name and a description, then click `Add workflow` to continue.
4. Newly created workflows will contain default start & end steps. You can edit the default steps by clicking `Edit step`, or move them to a different place in the workflow using the arrows that display on hover or the handlebars.

If your project has no workflows configured, you will see the following screen:

![Workflows screen - empty state](/images/docs/user-guides/workflows-empty-state.png)

## Initial setup

Once the workflow is created, you land on the setup screen:

![Content workflows initial setup](/images/docs/user-guides/workflows-setup.png)

Select initial setup options:

| Field               | Description                                                                                                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Model`             | Optional. Use the dropdown to select which models the workflow applies to.                                                                                                        |
| `Workflow override` | Optional. Use the dropdown to select roles that can choose to ignore the rules of the workflow to perform actions on content entries, in cases where changes are needed urgently. |

Click `Update configuration` to save your selection.

Next, you must configure the workflow steps.

## Add a workflow step

All workflows have two steps by default, the `Start` & `End` steps. This is the minimum number of steps a workflow can have, as each workflow must have a beginning and an end. You can add any number of steps in between them.

To add a new step, click `Add step`:

![Add a workflow step](/images/docs/user-guides/workflows-add-step.png)

## Step configuration

You will see the step configuration panel every time you add a new step or edit an existing one.

![Content workflows step configuration](/images/docs/user-guides/workflows-step-config.png)

| Field name         | Description   |
| ------------------ | ------------------ |
| `Step name`        | Enter a name for the step. |
| `Step color`       | Use the dropdown to select a color to identify the step.  |
| `Description`      | Optional. Write a description for the step.  |
| `Access`           | Select one or more roles that can move the step to the next or the previous one and who will be granted the edit permissions you configure next. |
| `PAT Access`           | Optional. Select the Permanent Auth Tokens (PATs) allowed to perform actions on entries in this step. This option is available only if your project includes a Permanent Auth Token and applies to all workflow steps except AI agent steps. Existing PAT permissions continue to apply, so you need to make sure the selected token has the necessary permissions to run this step.|
| `Edit permissions` | Use the radio buttons to choose whether the users with step access can edit entries or not.  |
| `Return to`        | Optional. Use the dropdown to select a step that entries can return to if necessary. You can only select a previous step. |
| `Publish to`       | Optional. Select one or more content stages to automatically publish content entries to when they move to this step. |

After configuring the step, click `Add step` for new steps, or `Update step` if you were editing an existing one.

Any [AI agents](/docs/hygraph-ai/ai-agents) configured in the workflow appears automatically as a workflow step.

### Publishing & unpublishing actions

In Workflows, **publishing actions** are automated. Content entries in the workflow cannot be published on demand; they are automatically published when they move to a specific step with a `Publish to` stage configured.

**Unpublishing actions** are allowed from any stage at any point, but republishing after that requires sending the entry back to the previous step to restart it.

<Alert theme="info" title="Pro Tip">

Unpublishing actions are not the same as moving a content entry back to a previous workflow step.

When you return a content entry to a previous step in the workflow, the content entry is not unpublished, and is still accessible online.

</Alert>

## Moving workflow steps

When you hover over a workflow step card, the following options display:

![Moving content workflow steps](/images/docs/user-guides/workflows-move-step.png)

Click on the arrow icons to move a step up or down in the workflow.

Consider that workflow steps can have `Return to` steps configured. Editing the position of a step in the workflow to a step before its `Return to` step, will break this logic and clear the configured return field.

In the following example, moving the step `Middle 2` before `Middle 1` (its configured  `Return to` step), will clear the return field configuration:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xajqjavr07w5m072kbov" caption="Content workflows - clear return step" />

<Alert theme="info" title="Pro Tip">

You can also use the six-dots handlebars to drag and drop a workflow step to move it.

</Alert>

## Edit a workflow step

To edit a workflow step, click the `Edit` button that displays when you hover over the step card:

![Edit a workflow step](/images/docs/user-guides/workflows-edit-a-step.png)

Check out the [Step configuration](#step-configuration) section of this document to see all possible actions on the edit screen.

## Delete a workflow step

To delete a workflow step, hover over the step card, click on the contextual menu to display the options in it, and click `Delete step`:

![Delete a workflow step](/images/docs/user-guides/workflows-delete-a-step.png)

You will need to confirm this action by clicking `Delete step` again on the confirmation popup. This action cannot be rolled back.

## Enable or disable a workflow

To enable a workflow, select the `Enable workflow` toggle that you can find at the top-right corner of the **Edit workflow** screen, or on the workflows table in `Project settings > Governance > Workflows`.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xw2ohv5x07vx0vsyzji2" caption="Enable or disable a workflow" />

When the workflow is enabled, its rules apply to all entries in the configured models.

To disable an enabled workflow, click on the toggle as well. When a workflow is enabled, the toggle reads `Disable workflow`.

## Edit a workflow

To edit a workflow, go to `Project settings > Governance > Workflows` and click on the workflow hat you want to edit on the table:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xb35hu9j07vx4rfidvmh" caption="Edit a workflow" />

The **Edit workflow** screen will display, and you can change its configuration.

## Delete a workflow

To delete a workflow, go to `Project settings > Governance > Workflows`, click on the context menu, and select `Delete Workflow`:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xb0ojawn07w568ubq92m" caption="Delete a workflow" />

You will need to confirm this action by clicking `Delete Workflow` again on the confirmation popup. This action cannot be rolled back.

## Workflows in content entries

When you open a content entry, the system checks if it is assigned to a workflow, and if editing is allowed.

**If editing is not allowed**, you will access a read-only version of the content entry. You can read the entry and leave comments, but you cannot modify the contents. You can also move it to the next step in the workflow if you have this permission.

**If editing allowed**, you can work on it normally.

On the sidebar, you can see what workflow step the entry is on:

![Workflows in content entries](/images/docs/user-guides/workflows_sidebar_widget.png)

<Alert theme="info" title="Pro Tip">

Even if the user does not have access & the Workflows sidebar widget is disabled, it will show which roles can work on the content entry.

</Alert>

If a workflow step is assigned to an [AI agent](/docs/hygraph-ai/ai-agents), the agent automatically starts processing as soon as an entry moves into that step. This ensures tasks run seamlessly within the defined workflow.

### Move the entry to a different step

If you have permission to move the entry to the next step in the workflow, the `Move to` button at the top-right of the screen will be enabled.

You can click `Move to`, to move the entry to the next step in the workflow, or click the arrow icon to display the workflow actions:

![Content workflows - entry actions](/images/docs/user-guides/workflows_entry_actions.png)

| Workflow action                    | Description                                                                                                                                                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Return to`                        | Select this option to return the content entry to its configured return step. This option is enabled only if the workflow step has a `Return to` step configured.                                                                   |
| `Move forward to`                  | Select this option to move the content entry to the next step in the workflow.                                                                                                                                                      |
| `Override workflow for this entry` | Select this option to override the workflow for the entry. When you override the workflow, you can perform any actions, just as if there wasn't a workflow configured. This option is enabled only if you have override permission. |

### Publish a content entry in the workflow

If you move a content entry into a step with `Publish to` configured, the entry will automatically be published to the configured stage. You can publish entries to intermediate content stages such as `QA`, or to `PUBLISHED`.

When publishing an entry to the `PUBLISHED` stage, you will have the option to publish it right away or to schedule publishing.

#### Publish now

This action publishes your content to the `PUBLISHED` stage, meaning it will be available online for others to consume. If your content entry contains unpublished assets or references, you will be prompted to publish those too.

Moving an entry to the next step & publishing at the same time is an atomic operation. This means both events will succeed or fail.

#### Schedule publishing

If you select scheduled publishing, the side sheet will open for you to schedule publication of the content entry.

<Alert theme="info" title="Pro Tip">

When you schedule an entry to publish to a stage, the workflow will move it to that stage but since publishing is scheduled in the future, it will not be published right away. If you open the content entry at this time, it will display as read-only.

In order to avoid workflow inconsistencies, the only way to edit this entry is to return it to the previous step, if you have the permission.

</Alert>

[Check out our scheduled publishing docs](/docs/developer-guides/content/scheduled-publishing) to learn how to schedule single entries or add them to a release.

## Webhooks for workflows

You can trigger a webhook when you move to a new workflow step. While [configuring your webhook](/docs/developer-guides/webhooks/webhooks-overview#configure-webhooks), choose the following settings:
- Under General, select the **Include payload** check box. This ensures that the webhook delivers a detailed payload including the workflow step, `workflowStep`.
- Under Actions, select **Transition Step**. This ensures that whenever your workflow transitions to a new step, the webhook is triggered.

![Webhooks for workflows](/images/docs/user-guides/content-workflows-transition-step.png)

## Workflows troubleshooting

### I can't edit content entries

If your role is configured to edit entries in a model, but you are not able to see this model or edit the content entries, you need to check permissions. Content workflows are an additional layer of control over permissions, but do not override them.


---
# Manage your project's environments

Source: https://hygraph.com/docs/developer-guides/project/manage-project-environments

Environments allow you to safely work on isolated instances of your project. They help you make changes to you schema and test new content structures without breaking your production systems.

![Manage environments](/images/docs/user-guides/project-guides/projectsettings-manage-environments.png)

## Create an environment

To create a new environment, we'll use the environment cloning flow:

![Create an environment](/images/docs/user-guides/project-guides/projectsettings-create-environments.png)


1. Navigate to the **Project Settings** tab in the left-hand sidebar of your Hygraph project.
2. Select **Environments** under general settings.
3. Click on the `Clone` button of the Master Environment card.
4. Fill in the form:
   - `Display name`: Provide a display name for your environment. This is the name that will be displayed in Hygraph.
   - `Endpoint alias`: This is created automatically as you type in your display name, but can be edited if you wish to. Your endpoint alias is the identifier used in the URLs of the webapp.
   - `Description`: This is where you can add a description for your new environment.
   - `Clone with context`: Checkbox that allows you to select whether you'd like to include the content from the master environment.
   - `Webhooks`: Checkbox that allows you to select whether you'd like to clone the project's webhooks. They will be disabled initially.


<Alert theme="error">
Users, Roles & Permissions, Permanent Auth Tokens, and billing will not be cloned between projects.
</Alert>

### Asset URLs change

Asset URLs will be different after a clone. Make sure to check for asset URLs stored in other places, such as source code or external systems.

Please note that, while in the past every single handle would have been updated, with the new asset system only the base URL changes on cloned environments.

<Alert theme="warning" title="Old URL change behavior">

Original asset URL:

`https://media.graphassets.com/6gB5FZ9mQiWHOu6Lt95p`

Asset URL after cloning:

`https://media.graphassets.com/<random new handle>`

</Alert>

With the new **Hygraph Asset Management System**, the following asset URL:

```
https://eu-west-2.graphassets.com/cm1q9b9c401cv07ut4wcgf2uj/cm2kmqsf6002a07ukg3z7sjzg
```

Would turn into something like this:

```
https://eu-west-2.graphassets.com/<new asset env id>/cm2kmqsf6002a07ukg3z7sjzg
```

Since the asset ID remains the same, you can simply run a search for the old asset environment ID and replace it with the new one.

## Switch environments

You must have at least two environments to be able to switch. To switch environments, click the **switch** dropdown in your Hygraph top bar. Select the environment that you want to switch to.

![Switch environments](/images/docs/user-guides/project-guides/projectsettings-switch-environments.png)

## Promote environments to master

You must have at least two environments to be able to do this. To promote an environment to master, simply click on the `Promote to master` link in the environment card.

![Promote environment to master](/images/docs/user-guides/project-guides/projectsettings-promote-env-to-master.png)

You will be prompted to provide a `New display name` and a `New API ID` for the current master environment being replaced. Fill in this information then click on `Promote to master`.

## Delete environments

You must have at least two environments to be able to do this. To delete an environment, simply click on the `Delete` link in the environment card. A warning will display to make sure you did not click on the link by mistake, so you need to confirm your choice by clicking on the `Delete environment` button to finalize the process.

![Delete environment](/images/docs/user-guides/project-guides/projectsettings-delete-environments.png)


---
# Manage your project's global information

Source: https://hygraph.com/docs/developer-guides/project/manage-project-info

Use this screen to edit your project's name and description, clone or share the project, grant Hygraph support temporary access for troubleshooting, leave the project, or delete it.

To access it, go to **Project settings > General > Project**.

![Project information](/images/docs/user-guides/project-guides/projectsettings-project-information.png)

## Permissions

What you can do on this screen depends on whether you are the project Owner and which permissions your role includes.

The **Admin** and **Developer** roles include **Change the name, picture and description of a project** by default. Editor, Contributor, and new custom roles do not, unless you add it.

| Action | Who can do it |
|---|---|
| Edit project details and picture | Users with **Change the name, picture and description of a project** permission |
| Enable or disable support access | Users with **Change the name, picture and description of a project** permission |
| Clone project | Project Owner only |
| Share project | Project Owner only |
| Support access | Users with **Change the name, picture and description of a project** permission |
| Leave project | Any member who is not the project Owner |
| Delete project | Project Owner only |

For more information, see [Roles - Project & Studio access](/docs/getting-started/access-and-permissions/management-api-permissions#roles-project-and-studio-access).

## Project details

This section shows your project's core identifiers, name, description, and picture. You can't edit **Id** and **Region**. Hygraph sets them when you create the project. You can copy the project ID here.

You can edit **Name** and **Description**. To change your project's picture, select **Upload** and choose a new image.

![Project details](/images/docs/user-guides/project-guides/projectsettings-project-details.png)

## Clone project

Only the project Owner can clone a project.

Cloning creates a full copy of your project, including its schema, content, and settings. Select **Clone project** to start. [This document](/docs/developer-guides/project/clone-your-project) covers the cloning process in detail.

![Clone your project](/images/docs/user-guides/project-guides/projectsettings-clone.png)

## Share project

Only the project Owner can enable public cloning.

Sharing lets other users clone your project using a public link. Select **Enable public cloning** to turn this on. Anyone with the public clone link can then clone your project. [This document](/docs/developer-guides/project/share-your-project) covers project sharing in detail.

![Share your project](/images/docs/user-guides/project-guides/projectsettings-share.png)

## Grant access to Hygraph support

Support access grants the Hygraph support team read-only access to your project so they can help you debug an issue. They can view your project but cannot make any changes while support access is enabled. To enable or disable support access, you need the **Change the name, picture and description of a project** permission.

Select **Allow the Hygraph team to access your project** to turn it on. Support access stays on until you turn it off yourself. Hygraph doesn't revoke it automatically.

Turn support access off once your issue is resolved.

![Support access](/images/docs/user-guides/project-guides/projectsettings-support-access.png)

## Leave project

If you are not the project Owner, you can leave the project instead of deleting it. After you leave a project, you lose access, and the project stays intact for the remaining members.

1. Select **Leave**.
2. Complete the survey explaining why you're leaving.
3. Type your project's name to confirm, then select **Leave**.

To rejoin later, a team member must invite you again.

![Leave project](/images/docs/user-guides/project-guides/projectsettings-leave-project.png)

## Delete project

Only the project Owner can delete a project. Other members see [Leave project](#leave-project) instead.

Deleting your project is permanent and cannot be undone.

1. Select **Delete project**.
2. Complete the survey explaining why you're deleting the project.
3. Type your project's name to confirm, then select **Delete**.

![Delete your project](/images/docs/user-guides/project-guides/projectsettings-delete.png)

## Related docs

- [Clone your Hygraph project](/docs/developer-guides/project/clone-your-project): Walk through the full cloning process step by step.
- [Learn about sharing your project](/docs/developer-guides/project/share-your-project): Understand what happens when you enable public cloning.
- [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions): Confirm which roles can access project settings.

---
# Manage your project's locales

Source: https://hygraph.com/docs/developer-guides/project/manage-project-locales

Locales define the languages available in your Hygraph project.

You can add multiple locales and configure schema fields to be localized. Once enabled on a field, content editors can provide values per locale.

<Alert theme="info" title="Looking for the API reference?">
Read the <a href="/docs/api-reference/content-api/localization">Localization API reference</a> for details.
</Alert>

## Access project locales

Locales are **environment-specific**. If you're working with a project using more than one environment, you must configure locales separately in each environment.

To manage locales:

1. Open your project.
2. Navigate to **Project settings > Locales**.
3. Select **Locales**.

![Project locales](/images/docs/user-guides/project-guides/projectsettings-locales.png)

## Add a locale

The default locale for new projects is **English**.

To add a new locale:

1. In your project settings, select a language from the **Display name** dropdown.
2. Click **+ Add**.

The new locale is now available for localized fields in this environment.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmm4lak79qz6d06w2mis3umfa" caption="Add a project locale" />

## Edit a locale

To update an existing locale:

1. In your project settings, click **Edit** next to the locale.
2. Update the configuration as needed.

Changes apply immediately to the current environment.

![Edit locales](/images/docs/user-guides/project-guides/projectsettings-locales-edit.png)

## Modify the default locale

Each project environment has one default locale. The default locale is used as the primary language fallback for content.

[AI Assist](/docs/hygraph-ai/ai-assist) uses the default locale for content generation and content improvement. Changing the default locale affects how AI Assist generates and enhances content.

To modify the default locale:

1. Click **Edit** next to your default locale.
2. Update the configuration. Ensure that the display name is a valid locale and it is not the same as any other locale in the project.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmm4lak9hqz7606w25dvlh55a" caption="Modify the default locale" />

## Delete a locale

You can delete any additional locale that is not set as default.

To delete a locale:

1. Open the context menu next to the locale that you want to remove from your project.
    - The context menu will only display for additional locales, as it is not possible to delete the default locale.
2. Select **Delete**.
3. Confirm the deletion.

A confirmation dialog appears before the locale is permanently removed.

![Delete locales](/images/docs/user-guides/project-guides/projectsettings-locales-delete.png)


---
# Work with multiple environments

Source: https://hygraph.com/docs/developer-guides/project/multiple-environments

Promoting schema changes to your master environment can put production content at risk. This doc covers two workflows for promoting changes safely: applying an isolated migration directly, or staging changes in a third environment before promotion.

## Why work with multiple environments

After you launch a Hygraph project into production, you'll continue improving it. Many improvements require schema changes, since your API's data and shape evolve with new requirements. Applying a schema change directly to your master environment affects your production websites or apps immediately, which puts your business at risk.

Hygraph supports multiple environments so you can iterate on your schema safely before finalizing a content model. An environment is a full copy of your project. Every project starts with a master environment, and your API endpoint reflects it directly. 

You can find your master environment API endpoint in **Project settings > Access > API Access > Endpoint > Content API**. Here's the endpoint for a master environment:

![Master environment endpoint example](/images/docs/user-guides/multiple-environments/multiple-environments-master-env-endpoint.png)

## Set up a development environment

To create a new environment cloned from your master environment:

1. Go to **Project Settings > Environments**.
2. Select the environment you want to clone from.
3. Click **Clone**.

    ![Clone master environment button in Environments screen](/images/docs/user-guides/multiple-environments/multiple-environments-clone-master-button.png)

4. Complete the clone form:
    - **Display name**: Set the environment name. 
    - **Endpoint alias**: Auto-completes from the display name.
    - **Accent color**: Set the environment's accent color.
    - **Description**: Add a description for the environment.
    - **Clone with content**: Clone existing content and assets into the new environment. Recommended if you want to test your development environment with real content.
    - **Webhooks**: Clone your project's webhooks into the new environment. The webhooks will be initially deactivated in the cloned environment.
        ![Clone new environment from Master Environment](/images/docs/user-guides/multiple-environments/multiple-environments-clone-from-master.png)

5. Click **Clone** to create the environment. Cloning can take time, depending on your project's size.

You now have a clone of your master environment to experiment on without affecting production.

Switch between environments using the environment dropdown in the top bar.

![Project environments](/images/docs/user-guides/multiple-environments/multiple-environments-environments.png)

## Content changes made during development

Building a new feature takes time, sometimes days, weeks, or months before it ships.

During that time, editors keep working in your master environment. Their changes exist only there. Your cloned development environment stays at the state it was cloned from, so promoting it to master would revert content back to that point, undoing everything editors added since.

<Alert theme="warning">

Promoting an environment to master means swapping that environment with master, so it becomes the new master.

</Alert>

To promote both your latest schema and your latest content, use one of these workflows:

- [Isolate changes and apply them to production](/docs/developer-guides/project/multiple-environments#isolate-changes-and-apply-them-to-production)
- [Use a third environment](/docs/developer-guides/project/multiple-environments#use-a-third-environment)

### Isolate changes and apply them to production

This workflow applies a set of changes from your development environment to your master environment, as a controlled migration. It requires you to:

1. [Start a content freeze](/docs/developer-guides/project/content-freeze#configure-a-freeze) on your master environment. Since this workflow applies changes directly to master with no buffer environment, freezing content is what protects in-progress editor work here.
2. Make your changes and test them.
3. Use the **Management SDK method** to [isolate the changes](/docs/api-reference/management-sdk/management-sdk-batchmigration#generate-a-diff) and then [apply those changes to production directly](/docs/api-reference/management-sdk/management-sdk-batchmigration#apply-schema-changes).
4. [Lift the content freeze](/docs/developer-guides/project/content-freeze#lift-a-freeze-early) once the migration completes.

<Alert theme="warning">

This method has some limitations when it comes to applying schema changes to your master environment. See [this document](/docs/api-reference/management-sdk/management-sdk-batchmigration#how-schema-changes-affect-the-target-environment) for details.

</Alert>

This workflow is generally safe: running the changes as a single migration means they succeed or fail as a whole, not individually, which reduces errors. If any step fails, Hygraph undoes all changes automatically.

<Alert theme="warning">

Use this workflow if you're on the **Growth plan**, since it includes only two environments total, including master.

It doesn't guarantee against issues, because you're applying a new schema to content that's already changed.

</Alert>

### Use a third environment

![Promoting environments flowchart](/images/docs/user-guides/multiple-environments/multiple-environments-promoting-envs-flowchart.png)

This workflow takes more steps, but it's the safest option. It requires you to:

1. Make your changes and test them.
2. Isolate your changes. Use [environment diffing](/docs/api-reference/schema/environment-diffing) to do this, or find and isolate them yourself if you kept track of them in code.
3. [Start a content freeze](/docs/developer-guides/project/content-freeze#configure-a-freeze) on your master environment. This prevents editors from creating, editing, or publishing content while you promote `staging` to master.
4. Clone a third environment named `staging` from `master`, right before deploying your feature. Cloning close to deployment time means `staging` carries master's most recent content.
5. Apply the changes you've made in your development environment to `staging` too. Use the **Management API**, as shown [here](/docs/api-reference/schema/environment-diffing#3-apply-schema-changes). For small schema changes, like deleting or renaming a field, applying them manually may be more practical.
6. Run tests on your `staging` environment to confirm there are no conflicts between the new schema and the updated content.
7. Promote your new `staging` environment to be the new master environment, containing the most recent content and schema changes. See [Promote the development environment to master](/docs/developer-guides/project/multiple-environments#promote-the-cloned-environment-to-master) for details.
8. [Lift the content freeze](/docs/developer-guides/project/content-freeze#lift-a-freeze-early). Editors regain the ability to save and publish immediately.

If you run into issues with this method, roll back by promoting the old master environment to master again. This may require rolling back your frontend too.

<Alert theme="warning">

This method has some limitations when it comes to applying schema changes to your master environment. See [this document](/docs/api-reference/schema/environment-diffing#environment-diffing-limitations) for details.

</Alert>

## Promote the cloned environment to master

Once you've made all the necessary changes to your application's codebase, promote the cloned environment to become the new master environment. Click **Promote** on the cloned environment, in **Project settings > Environments**.

<Alert theme="warning">

If you haven't already started a content freeze as part of the workflow above, start one now before promoting. This prevents editors from losing in-progress work in the environment being replaced. See [Content Freeze](/docs/developer-guides/project/content-freeze#configure-a-freeze).

</Alert>

![Promoting the Development Environment to Master](/images/docs/user-guides/multiple-environments/multiple-environments-promote-to-master.png)

You need to rename the old master environment to avoid a naming clash. Filling in **New display name** auto-fills **New API ID**.

![Promoting the Development Environment to Master](/images/docs/user-guides/multiple-environments/multiple-environments-promotetomaster-screen.png)

Click **Promote** to confirm. Hygraph renames the cloned environment to `master`, and it becomes your master environment from that point on.

After promoting, deploy your code changes so your production websites or applications match the newly promoted environment. To minimize downtime, automate promotion and deployment in a CI/CD pipeline using the Management API or SDK.

<Alert theme="warning">

Coordinate deployment order between your Hygraph project and your frontend applications. When you add models or fields, deploy the Hygraph schema changes first, then the frontend. When you remove models or fields, reverse that order. This prevents your frontend from requesting data that doesn't exist yet.

</Alert>

### Tokens and environment promotion

![Permanent Auth Token](/images/docs/user-guides/multiple-environments/multiple-environments-token.png)

Tokens hold two kinds of information: an `ID` and the environment it's associated with (`master`, `staging`, `development`).

To see this yourself, copy a token from your project and paste it into <Link href="https://jwt.io/" target="_blank"><b>jwt.io</b></Link>. Under `Payload: data` on the right, you'll find the environment your token targets.

![Permanent Auth Token](/images/docs/user-guides/multiple-environments/token-audience.png)

To keep a token working after you promote an environment, create it in your master environment first, then clone that environment to [set up your development environment](/docs/developer-guides/project/multiple-environments#set-up-a-development-environment).

Cloning an environment clones its tokens too, so the new environment's tokens share the same internal `ID` as the originals. After promotion, these tokens keep working, because the environment and the `ID` still match.

<Alert theme="info" title="Pro Tip">
Once you promote `development` to `master`, the token tied to the `development` environment stops working.

If you later clone `master` again to create a new `development` environment, that token starts working again, since the project `ID` and environment match once more.
</Alert>

## Related docs

- [Management SDK](/docs/api-reference/management-sdk/management-sdk): Apply schema changes programmatically.
- [Environment diffing](/docs/api-reference/schema/environment-diffing): Isolate schema changes between environments.
- [Environments API reference](/docs/api-reference/basics/environments): Manage environments through the API.

---
# Share your project

Source: https://hygraph.com/docs/developer-guides/project/share-your-project

You can share your existing project's master environment as a template with others.

Inside your project settings, you can **enable public cloning**. You can then decide whether you want to share existing content, assets, and/or webhooks.

![Project settings](/images/docs/user-guides/project-settings-share.png)

Anyone with the public cloning link can clone this project into their own accounts. Check out our document on [Public cloning](/docs/developer-guides/project/clone-your-project#public-cloning) to know more.

<Alert title="Pro Tip" theme="info">

You can use this to create your own starter project and share it with other people.

</Alert>


---
# Update your password

Source: https://hygraph.com/docs/developer-guides/project/update-your-password

To change your account password you will need to logout, and choose "forgot password" from the login page to send you an email to set a new one.

If you're logged in with Facebook, GitHub, or Google, you can change your password there and you'll be logged in automatically with Hygraph.


---
# Usage dashboard

Source: https://hygraph.com/docs/developer-guides/project/usage-dashboard

The Usage dashboard gives you direct visibility into your project's API and asset consumption. If you see any unexpected behavior, such as slow responses, errors, or limits being hit, this is where you start.

To access it, navigate to **Project Settings > General > Usage**.

![Usage dashboard](/images/docs/developer-guides/project-guides/usage-dashboard.png)

Use this dashboard to:
- Rule Hygraph in or out during incident triage without filing a support ticket.
- See whether a spike is hitting a plan quota or an operational limit, and which metric specifically.
- Track API calls and asset bandwidth per project against your plan limits.
- Monitor RPS, concurrency, and request size per environment before they cause dropped requests.
- Identify which environment is driving consumption without cross-referencing external tools.

## Access

The **Usage** tab is visible to Admin and Developer roles by default. To grant access to other users, assign them the **Read observability data** [Management API permission](/docs/getting-started/access-and-permissions/management-api-permissions#roles-experimental-ai-usage).

Data in this dashboard is updated every hour.

To query the same metrics programmatically, see [Usage metrics API reference](/docs/api-reference/basics/usage-metrics).

## Project quotas

Project quotas show how much of your plan's allocated resources your project has consumed over your billing period. These metrics are scoped to the project, not individual environments. Approaching a limit here means you are approaching a plan boundary, not an operational threshold.

A visual threshold indicates when consumption is approaching the project's limit:

- Orange: 80% of the limit
- Red: 95% of the limit

If you are consistently approaching or exceeding your plan limits, see [Manage plan](/docs/developer-guides/project/update-billing#manage-plan).

### Asset bandwidth

The **Asset bandwidth** chart shows the total data transferred for assets, such as images, video, and documents, served from your project. The chart shows daily consumption as a bar chart and a cumulative indicator. Hover over any bar to see the exact value for that day.

Example: 40 / 100 GB shows the total asset bandwidth for your billing period against your plan limit.

![Asset bandwidth](/images/docs/developer-guides/project-guides/usage-dashboard-asset-bandwidth.png)

### API calls

The **API calls** chart shows total requests made to your Content API. The chart shows daily consumption as a bar chart and a cumulative indicator. Hover over any bar to see the exact value for that day. 

Example: 47K / 500K calls shows the total API calls for your billing period against your plan limit. 

![API calls](/images/docs/developer-guides/project-guides/usage-dashboard-api-calls.png)

## Tech safeguards metrics

Tech safeguards metrics show the operational limits that govern how your API handles traffic at a given moment. These limits exist independently of your plan quotas. Exceeding them affects request behavior directly. For more information on tech safeguards in your plan, see [API limits](/docs/api-reference/basics/api-limits).

You can filter tech safeguard metrics by environment and time range.

- **Environment**: Filters all metrics to a specific environment.
- **Time range**: Available options are last 7 days, last 30 days, last 6 months, and last 12 months.

Metrics reflect activity up to the last hourly update. For same-day activity, check back after the next update cycle. Real-time data and minute-level granularity are not available.

### Request Activity

A spike in blocked requests is the clearest signal that something hit an operational ceiling. The **Request Activity** chart shows two series: requests within limit and requests blocked. This lets you see exactly when that happened and how sustained it was. Hover over any point to see a breakdown tooltip for that day.

![Request Activity](/images/docs/developer-guides/project-guides/usage-dashboard-request-activity.png)

### Concurrent operations

The **Concurrent operations** chart shows separate sparkline charts for concurrent queries and mutations against your project's concurrency limit. Each chart provides concurrent requests data for a given day. Hover over the limit line on any chart to see the following details for a day:

- Maximum concurrent queries / mutations that day
- Your plan's concurrency limit
- Number of requests blocked that day

If your concurrent requests cross your plan limit, they may be blocked. A red dot on the chart indicates that requests were blocked that day.

For more information on concurrency operations in your plan, see [API limits - Concurrent operations](/docs/api-reference/basics/api-limits#concurrent-operations).

![Concurrent operations](/images/docs/developer-guides/project-guides/usage-dashboard-concurrent-operations.png)

### Request size

The **Request size** chart shows separate sparkline charts for query and mutation request sizes against your project's configured limit. Hover over the limit line on any chart to see the following details for a day:

- Maximum request size for queries / mutations that day
- Your plan's request size limit
- Number of requests blocked that day

Requests that exceed the size limit may be blocked before execution. For more information on request size in your plan, see [API limits - Request size](/docs/api-reference/basics/api-limits#request-size).

![Request size](/images/docs/developer-guides/project-guides/usage-dashboard-request-size.png)

### RPS (Requests per second)

The **RPS** chart shows query and mutation requests per second against your project's rate limit as a sparkline. Hover over the limit line to see the following details for a day:

- Maximum RPS recorded that day
- Number of requests blocked that day

Sustained activity near the threshold indicates your client is sending requests faster than the project is configured to accept. This does not necessarily mean that requests are failing yet, but that the margin is reduced. A red dot on the chart indicates that requests were blocked that day. 

For more information on requests per second in your plan, see [API limits - Requests per second](/docs/api-reference/basics/api-limits#requests-per-second).

![RPS](/images/docs/developer-guides/project-guides/usage-dashboard-rps.png)

---
# Remote data overview

Source: https://hygraph.com/docs/developer-guides/remote-data/overview

## Overview

![remote-sources-mainscreen.png](/images/docs/user-guides/remote-sources/remote-sources-mainscreen.png)

A Remote Source is a custom resolver entry point for your schema that allows data to be sourced from an external third-party web service and accept field values from other Hygraph fields as arguments.

With Remote Sources, our [Content Federation](/docs/getting-started/fundamentals/content-federation) utility, it's possible to add content from other systems and sources to the Hygraph API without having to migrate the content itself.

You can use Remote Sources to add Remote Fields to your schema, at the model or at the top level:

At the model level, you can use them to enrich data, which can then be queried in the context of the model they are a part of.

At the top level, you can use them to fetch [remote data](/docs/developer-guides/remote-data/remote-content) - unrelated to Hygraph - that can be consumed by your frontend alongside your Hygraph data.

## What you can do

Remote Sources enable teams to build optimized, data-rich applications where they can use existing services paired with new microservices to build user-friendly applications with a single content entry point.

There are many use cases where moving content into the CMS isn't possible or desirable. Examples include content for which there is a different system of record (e-commerce/product data like price or availability, content from a different vendor like Github or IMDBT, etc) and content that is stored in legacy systems that can't be easily migrated.

Remote Sources allow customers to create a single GraphQL API with content from all these different sources, providing flexibility for front-end developers and downstream applications.

## Important concepts

### Remote Source

A system or product that holds content that needs to be combined with content in Hygraph and which can be queried through a RESTful or GraphQL API. A single Remote Source can have different types of content (e.g., an e-commerce system might have products, categories, prices, etc). Every Remote Source has a unique (base) URL, such as Github, Shopify, Hasura, or a custom backend application.

### Remote content

These are fields that you can add to a model to fetch data from a Remote Source. There are two types: Remote Fields and Top-level Remote Fields.

### Remote Field

A field inside a Hygraph model that connects specific remote data to an entry of that model. Remote Fields are always related to a single Remote Source and a single custom type. RESTful Remote Fields are configured with a path to a specific endpoint in the Remote Source, such as user details from Github, or price & availability from Shopify.

### Top Level Remote Field

A field inside the Query system model in Hygraph. These fields are used to fetch remote data outside the context of a regular model, which is then sent to your frontend alongside your Hygraph data. This [Content Federation](/docs/getting-started/fundamentals/content-federation) utility eliminates the need to make separate API requests for data inside & outside of Hygraph.

### Custom Type

A <Link href="https://graphql.org/learn/schema/" target="_blank">GraphQL type</Link> that is used for content coming from a Remote Source. The custom types are combined with the auto-generated types inside Hygraph to create a single schema for content inside Hygraph and in the Remote Source. For RESTful Remote Sources, custom types need to be defined explicitly using <Link href="https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51" target="_blank">SDL</Link> for all URL paths that will be queried in the Remote Source. For GraphQL Remote Sources, the custom types are auto-generated by using <Link href="https://graphql.org/learn/introspection/" target="_blank">introspection</Link> on the Remote Source.

### Custom Input type

A <Link href="https://graphql.org/learn/schema/#input-types" target="_blank">specific kind of GraphQL type</Link> which is used to define input parameters for queries to Remote Sources.




---
# Add remote data to your model

Source: https://hygraph.com/docs/developer-guides/remote-data/remote-content

## Overview

This document section explains how to add Remote Fields to models in your project. The flow is the same for [Remote Fields](/docs/developer-guides/remote-data/remote-field#remote-fields) added to regular models, and [Top-level Remote Fields](/docs/developer-guides/remote-data/remote-field#top-level-remote-fields).

<Alert theme="info" title="Pro Tip">
If you don't know the difference between Remote Fields and Top-level Remote Fields, [check out this document](/docs/developer-guides/remote-data/remote-field).
</Alert>

## Add Remote Field

After [adding a Remote Source](/docs/developer-guides/remote-data/remote-sources), it's now time to add a Remote Field to a model. This is slightly different for RESTful remote sources vs. GraphQL Remote Sources, so we will explain this step for each of them separately.

<Alert theme="info" title="Before you add remote data">
Remote Fields & Top-level Remote Fields can only be added [after at least one Remote Source of the corresponding type - REST or GraphQL - has been configured](/docs/developer-guides/remote-data/remote-sources).
</Alert>

### REST

First, select a Remote Field type:
- If you're adding a [Remote Field](/docs/developer-guides/remote-data/remote-field#remote-fields) to a regular model: Navigate to the **Schema builder**, select the model that will contain your Remote Field, scroll down the field type list located on the right side of the screen, and select the `REST` field.
- If you're adding a [Top-level Remote Field](/docs/developer-guides/remote-data/remote-field#top-level-remote-fields) to the `Query` model: Navigate to the `Query` model in your project schema, then select the `REST` field from the **Add fields** list located on the right side of the screen.

![REST Remote Field](/images/docs/user-guides/remote-sources/creating-remote-field-rest.png)

Then, follow these instructions:

1. In the **Create Field** dialog, fill in the `Display name`, `API ID`, and optionally add a `Description`.
2. If the remote API for this field returns an array of the chosen custom type instead of a single object, make sure to select the `Allow multiple values` checkbox, under **Field options**. For instance, if you defined your custom type to be `Product`, but the remote API returns an array of `products`, you need to make use of the `Allow multiple values` option, so the request won't return an error.
3. Select a previously configured `Remote Source` and an `HTTP Method` using the dropdowns. For `Return type`, select one of the custom types that you configured for the Remote Source. This custom type needs to (partially) match with the response of the API path that will be requested in this field. You can find detailed information on creating custom types [here](/docs/developer-guides/remote-data/remote-sources#create-a-custom-type-definition). Alternatively, it's possible to set the response to be a scalar type (string, Boolean, JSON, etc).

        [Click here to learn how to use a custom type definition.](/docs/developer-guides/remote-data/remote-content#how-to-use-a-custom-type-definition)

        <Alert theme="info" title="Remember">
        Adding a [Remote Source](/docs/developer-guides/remote-data/remote-sources) to your project is a prerequisite in order to add a remote field to a model.

        [Defining your custom types](/docs/developer-guides/remote-data/remote-sources#create-a-custom-type-definition) is the step of remote source configuration where you specify the shape of the response coming from a `REST` API. It's what allows you to query the `REST` API as if it were native `GraphQL`. These Custom Type Definitions use `GraphQL SDL` (Schema Definition Language).
        </Alert>
4. You can optionally add `Input arguments`. You can add an input argument by selecting a custom input type for the Remote Source and providing an `API ID` for the inputs, which can be used in the configuration of the `URL Path`. Multiple input arguments can be added by clicking `+Add`.

        [Click here to learn how to use a custom input type definition.](/docs/developer-guides/remote-data/remote-content#how-to-use-a-custom-input-type-definition)

        <Alert theme="info" title="Would you like to know more?">
        [Here's an example of working with custom input types.](/docs/developer-guides/remote-data/remote-data-examples#working-with-custom-input-types)
        [Defining your custom types](/docs/developer-guides/remote-data/remote-sources#create-a-custom-type-definition) is the step of remote source configuration where you specify the shape of the response coming from a `REST` API. It's what allows you to query the `REST` API as if it were native `GraphQL`. These Custom Type Definitions use `GraphQL SDL` (Schema Definition Language).
        </Alert>
5. Configure the `Path` that will be queried for this Remote Field. This path will be added to the Remote Source base path to get a resulting endpoint. In the path definition, you can use handlebars notation (start by typing a `{`) to use fields from the document or from the input arguments, if defined. This way, you can dynamically build a URL path using field values from the same content model or from an input parameter value. As an example, if the model has a field called `userId` , it's possible to build a path that looks like this: `/users/{{doc.userId}}/`repos.

<Alert theme="info" title="Pro Tip">
You can make it possible for Editors to select the input arguments.

Imagine you've just configured a REST remote source where you added an input type definition called "articles", and want your Editors to be able to select the content entries of a specific user. What you'd do here, is add a single line field field, let's call it `username`, and then add your REST remote field, which we'll call `articles` for this example.

We'd follow the same steps that we explained above for the `Remote source`, `Method` and `Return type`.

We won't add an `Input argument` here. Instead we'll go to `Path`, and at the end of the URL path that we type in, we'll write `doc` to indicate that we're referencing the document we're editing, and select `{{doc.username}}`, where `username` corresponds to the field that we added before as an input.

What we just did is add a REST Remote Field to our model in a way it can use metadata from a document to query it.

In this example, what Editors would do is simply input a `username` in the content entry, and this would result in only `articles` from that `username` being fetched in a query.

Would you like to see this more in depth? [Check out Tim's video](/docs/developer-guides/remote-data/remote-data-examples#add-any-rest-source).
</Alert>

### GraphQL

<Alert theme="warning" title="Feature availability">
At the moment, **Hygraph Studio** does not support this feature.
</Alert>

First, select a Remote Field type:
- If you're adding a [Remote Field](/docs/developer-guides/remote-data/remote-field#remote-fields) to a regular model: Navigate to the **Schema builder**, select the model that will contain your Remote Field, scroll down the field type list located on the right side of the screen, and select the `REST` field.
- If you're adding a [Top-level Remote Field](/docs/developer-guides/remote-data/remote-field#top-level-remote-fields) to the `Query` model: Navigate to the `Query` model in your project schema, then select the `REST` field from the **Add fields** list located on the right side of the screen.

![Remote Field - GraphQL](/images/docs/user-guides/remote-sources/creating-remote-field-gql.png)

Then, follow these instructions:

1. In the `Create Field` dialog, fill in `Display name`, `API ID`, and optionally add a `Description`.
2. Select a previously configured `Remote Source` and an HTTP `Method`.
3. You can **optionally** add `Input arguments`. You can add an input argument by selecting a `custom input type` for the remote source, and providing an `API ID` for the inputs, which can be used in the configuration of the URL `Path`. Multiple input arguments can be added by clicking on `+Add`.

        [Click here to learn how to use a custom input type definition](/docs/developer-guides/remote-data/remote-content#how-to-use-a-custom-input-type-definition).

        <Alert theme="info" title="Would you like to know more?">
        [Here's an example on working with custom input types](/docs/developer-guides/remote-data/remote-data-examples#working-with-custom-input-types).
        </Alert>

4. Now select the `Query` that will be the entry point into the remote schema from the tree that is shown at the bottom of the `Create Field` dialog. This tree is populated using introspection, and will show all available queries in the Remote Source.

        - When selecting a query, the tree unfolds to show all `arguments` for that query (in purple), available `sub-queries` (enabled and showing type in blue), and available `fields` or `scalars` (disabled and showing with type in grey). It's important to note that the selected (sub)query will determine which data from the remote source can be queried through Hygraph. **All arguments, scalars, and subqueries in the Remote Source that are below the selected query will be queryable**. Other values and queries in the tree will _not_ be queryable unless they are part of another Remote Field.
        - Arguments that are required show a purple asterisk (\*) next to their ID, although there is no validation on the value done inside Hygraph. It's possible to use handlebars notation inside a parameter field. Start by typing `{`, which will bring up suggestions based on the fields on your model.

            ![GraphQL query selection](/images/docs/user-guides/remote-sources/graphql-query-selection.png)

        - For queries that return a single value, it's also possible to select a sub-query as the entry point. **Note that this means that only fields inside the selected sub-query are available to be queried through Hygraph.**

## How to use a custom type definition

[After successfully defining the custom type for your remote source](/docs/developer-guides/remote-data/remote-sources#create-a-custom-type-definition), it can be used on your Remote Field (REST).

1. Open any of your models and either create a new Remote Field (REST) from the right hand field picker or edit an existing Remote Field (REST). On that Remote Field, select the just created custom type under Return type.

    ![Using a custom type definition](/images/docs/user-guides/remote-sources/using-custom-type-definition.png)

2. When querying your Remote Field, you will now have a sub-selection of the fields you defined. In this case, the Remote Field is called `githubInfo`

   ```graphql
   {
     authors {
       id
       name
       githubInfo {
         id
         name
         url
       }
     }
   }
   ```

## How to use a custom input type definition

1. On your Remote Field, you can now select the [custom input type you defined for your remote source](/docs/developer-guides/remote-data/remote-sources#create-a-custom-input-type-definition) as an `Input Argument`. For this, open one of your models and add a new Remote Field or edit an existing one.
2. Click on `+Add` under `Input arguments`, select the input type you just created, and give it an API ID.

   ![Using a custom input type definition](/images/docs/user-guides/remote-sources/using-custom-input.png)

3. After saving the field, you can head into the API Playground and test the just created input argument, which will work like this:

    ```graphql
    {
      pages {
        id
        product(product: { productId: "123" }) {
          name
          slug
          price
        }
      }
    }
    ```

## Advanced settings (Cache)

<Alert theme="info">
Advanced settings apply to both types of Remote Fields.
</Alert>

1. Although `HTTP` headers can be configured on a **Remote Source** - meaning on all requests for all fields that use this remote source - it's also possible to add additional `HTTP` headers on a specific **Remote Field**. The headers are additive, but if you configure the same header both on the field and on the remote source, the value from the Remote Field will take precedence. Additionally, it's possible to have all client headers to Hygraph forwarded to the Remote Source. This can be useful to forward user context to the remote server, for example.
2. By default, Hygraph caches queries that include Remote Fields using a TTL cache with a value of 15 minutes. The TTL can be overridden in the Remote Field settings dialog (minimum TTL value is 60 seconds). However, please note that if the Remote Source sends a cache-control response header, this will override the cache configuration in Hygraph.
3. Optionally set field visibility. For the default setting of `read-only`, the Remote Field is displayed in the content form with a link to the API playground. If the field visibility is set to `API only`, the Remote Field is not displayed in the content form but is still available to query through the API.

## Query remote data

### Query Remote Fields

After configuring the Remote Field, it's added to the Hygraph schema and immediately queryable through the API. Press `CTRL/CMD+Space` or open the Explorer view to see the available sub-fields inside the Remote Field.

<Alert theme="info">
Note that the Remote Source prefix is added in front of the type for easy identification.
</Alert>

Below screenshots demonstrate what this looks like for the User endpoint of the Github API:

![Remote Field - Query](/images/docs/user-guides/remote-sources/remote-field-query.png)

![Remote Field - Explorer](/images/docs/user-guides/remote-sources/remote-field-explorer.png)

The following example fetches information from within a model:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  products {
    slug
    fieldremoteproducts {
      id
      slug
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "products": [
      {
        "slug": "hoodie",
        "fieldremoteproducts": {
          "id": "cl3jub8gkslb90euj2n3ea357",
          "slug": "hoodie"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

In this case, the Remote Field is related to the `Products` model, and it only fetches data related to it.

### Query Top Level Remote Fields

Top Level Remote Fields can be queried outside the context of a model.

In the following example, `product` is not a model, but a Top Level Remote Fields, completely unrelated to Hygraph content.

<Tabs panelHeight={200}>
  <TabsItem label="Query">

```graphql
{
  products {
    id
    slug
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "products": [
      {
        "id": "clilfku1s007r0bvoci5ho12i",
        "slug": "hoodie"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

Instead of just enriching content that is in Hygraph, you can use the Hygraph API as a passthrough layer, where your frontend makes requests to APIs that don't relate to Hygraph.

With this [Content Federation](/docs/getting-started/fundamentals/content-federation) feature, you can use Hygraph to pipe everything through to your frontend without the need of making two separate requests.

Let's compare this to fetching information from within a model:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  products {
    slug
    fieldremoteproducts {
      id
      slug
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "products": [
      {
        "slug": "hoodie",
        "fieldremoteproducts": {
          "id": "cl3jub8gkslb90euj2n3ea357",
          "slug": "hoodie"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

In this case, the Remote Field is related to the `Products` model, and it only fetches data related to it.



---
# Examples

Source: https://hygraph.com/docs/developer-guides/remote-data/remote-data-examples

## Custom remote source and field configuration

In this video, Bryan uses <Link href="https://www.federatethis.com/" target="_blank">Federate this</Link> - our collection of mock APIs and information for federated data sources in GraphQL - to show you how to add data from a remote API to your Hygraph project step-by-step.

<VideoEmbed videoId="mANTy5_OTQo" />

### Configure the remote source

Navigate to the **Schema builder** and click on `+Add` next to **Remote sources** to create a new one. Use the following information:

| Field          | Input                              |
| -------------- | ---------------------------------- |
| `Display name` | Third Party APIs                   |
| `Prefix`       | ThirdPartyApIs                     |
| `Type`         | Select `REST`                      |
| `Base URL`     | `https://www.federatethis.com/api` |

**Custom type definition:**

Click `+ Add custom type definition` and we'll paste the product type and products array from <Link href="https://www.federatethis.com/routes/products/" target="_blank">Federate This</Link>:

```graphql
type Product {
    id: Int
    name: String
    price: Int
    description: String
    image: String
    category: String
    rating: Float
    numReviews: Int
    countInStock: Int
}

type Products {
    data: [Product]
}
```
We'll also add the following under `Products`:

```graphql
type ProductMeta {
  data: Product
}
```
What we just added will have a data field that will bring a singular product.

Click `Add` at the top-right corner of your screen to create the remote source.

Once the remote source is created, you can use it to add a remote field.

### Configure remote field

After configuring our remote source, go to **Schema > Query** and add a top-level remote field, which will allow us to connect our products list as data directly in our API.

To add your remote field, click on `REST` from the right sidebar and use the following information:

| Field           | Input                                                        |
| --------------- | ------------------------------------------------------------ |
| `Display name`  | Products                                                     |
| `API ID`        | products                                                     |
| `Remote source` | `Third Party APIs` is selected by default. Leave it as it is |
| `Method`        | `GET` is selected by default. Leave it as it is              |
| `Return type`   | Use the dropdown to select `ProductMeta`                     |
| `Path`          | `/products`                                                  |

Click `Add` at the bottom of the screen to create your remote field.

<Alert theme="info" title="Would you like to check if it works?">
Go to the API Playground and try out the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  products {
    data {
      name
      price
      id
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "products": {
      "data": [
        {
          "name": "Product 1",
          "price": 100,
          "id": 1
        },
        {
          "name": "Product 2",
          "price": 200,
          "id": 2
        },
        {
          "name": "Product 3",
          "price": 300,
          "id": 3
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

If you run the query, it should return information on three sample products.
</Alert>

If we wanted to bring specific information into a **Product** model, we'd have to add a Remote Field into that model.

If you do not have a **Product** model yet, you can go to your Schema and click `+ Add` next to Models and use the following information to create it:

| Field           | Input         |
| --------------- | ------------- |
| `Display name`  | ProductPage   |
| `API ID`        | productPage   |
| `Plural API ID` | productsPages |

Let's also add some fields to this model. We won't be adding price or any other information that is otherwise in out API. We will only add fields that we want to add to our data and that Editors will be able to work with.

We'll start with a `single line text` field that we'll use as a title:

| Field                | Input                |
| -------------------- | -------------------- |
| `Display name`       | Title                |
| `API ID`             | title                |
| `Use as title field` | Select this checkbox |

We'll add a `slug` field:

| Field           | Input                        |
| --------------- | ---------------------------- |
| `Display name ` | Slug                         |
| `API ID`        | slug                         |
| `Lowercase`     | Leave this checkbox selected |

We'll add a `Rich Text` field:

| Field          | Input |
| -------------- | ----- |
| `Display name` | Body  |
| `API ID`       | body  |

We need to associate the data in this model with the data that's in our API, and for that we'll add another `single line text` field, using the following information:

| Field          | Input  |
| -------------- | ------ |
| `Display name` | API ID |
| `API ID`       | apiId  |

At this point we're ready to add our remote field. We'll scroll down the right sidebar and add a `REST` field using the following information:

| Field           | Input                                                        |
| --------------- | ------------------------------------------------------------ |
| `Display name`  | Product data                                                 |
| `API ID`        | productData                                                  |
| `Remote source` | `Third Party APIs` is selected by default. Leave it as it is |
| `Method`        | `GET` is selected by default. Leave it as it is              |
| `Return type`   | Use the dropdown to select `ProductMeta`                     |
| `Path`          | `/product/{{doc.apiId}}`                                     |

Click `Add` to save your remote field.

Let's create an entry for our **ProductPage** model. Navigate to **Content editor > ProductPage** and click `+ Add entry`.

We'll use the following information:

| Field    | Input                                                                                   |
| -------- | --------------------------------------------------------------------------------------- |
| `Title`  | Product 1 with extra data                                                               |
| `Slug`   | product-1                                                                               |
| `Body`   | Use the dropdown tos elect Heading 2 and write "This is a headline".                    |
| `API ID` | This is where we will write the API ID of our product. IN this example we'll write "1". |

We'll click `Save & publish` and go to the API Playground to test this.

Let's run the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  productPages {
    apiId
    body {
      html
    }
    slug
    title
    productData {
      data {
        price
        rating
        numReviews
        description
        countInStock
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "productPages": [
      {
        "apiId": "1",
        "body": {
          "html": "<h2>This is a headline</h2><p></p>"
        },
        "slug": "product-1",
        "title": "Product 1 with extra data",
        "productData": {
          "data": {
            "price": 100,
            "rating": 4.5,
            "numReviews": 10,
            "description": "This is product 1",
            "countInStock": 10
          }
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

This query brings all the information we just added in to the content entry that we created, which comes from Hygraph's data, and also includes the productData data, which comes from the API and is associated through the `API ID` field we added earlier.

Now imagine you also want to add your product reviews here. <Link href="https://www.federatethis.com/routes/reviews/" target="_blank">Federate this</Link> has sample reviews that we can use to try this. We'll go back into the schema builder and edit our remote source by adding 3 new custom type definitions.

In our remote source, we'll click on `+ Add new custom type definition`. We'll do this three times, to add the following types:

<Tabs panelHeight={220}>
  <TabsItem label="Review">

```graphql
type Review {
    id: Int
    product: Int
    productSlug: String
    name: String
    rating: Float
    comment: String
}
```

  </TabsItem>
  <TabsItem label="Reviews">

```graphql
type Reviews {
    data: [Review]
}
```

  </TabsItem>
  <TabsItem label="ReviewMeta">

```graphql
type ReviewMeta {
    data: [Review]
}
```

  </TabsItem>
</Tabs>

Don't forget to click `Save` at the top-right of your screen to update your remote source.

Next, we're going to add this to our **ProductPage** model as a `REST` remote field. To do this, navigate to **Schema builder > ProductPage**, select the `REST` field from the right sidebar, and use the following information:

| Field           | Input                                                        |
| --------------- | ------------------------------------------------------------ |
| `Display name`  | Product Reviews                                              |
| `API ID`        | productReviews                                               |
| `Remote source` | `Third Party APIs` is selected by default. Leave it as it is |
| `Method`        | `GET` is selected by default. Leave it as it is              |
| `Return type`   | Use the dropdown to select `ReviewtMeta`                     |
| `Path`          | `/reviews/product/{{doc.apiId}}`                             |

Click `Add` to save your remote field.

The way we have set this up allows for the product details and the reviews from that product to pull from a single API ID, which we included in the `API ID` field that we added to our schema earlier and to which we assigned a value in the sample entry we created.

Now we can go back to the API Playground to test this using the following query:

<Tabs panelHeight={600}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  productPages {
    apiId
    body {
      html
    }
    slug
    title
    productData {
      data {
        price
        rating
        numReviews
        description
        countInStock
      }
    }
    productReviews {
      data {
        comment
        name
        rating
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "productPages": [
      {
        "apiId": "1",
        "body": {
          "html": "<h2>This is a headline</h2><p></p>"
        },
        "slug": "product-1",
        "title": "Product 1 with extra data",
        "productData": {
          "data": {
            "price": 100,
            "rating": 4.5,
            "numReviews": 10,
            "description": "This is product 1",
            "countInStock": 10
          }
        },
        "productReviews": {
          "data": [
            {
              "comment": "These shoes are both the mostly comfortable and the most stylish I have ever owned.",
              "name": "Person Personson",
              "rating": 4.5
            },
            {
              "comment": "These would be better if they were red. I suppose they aren't bad, but they aren't good either.",
              "name": "Second Person",
              "rating": 2.5
            },
            {
              "comment": "I've worn these for 3 years and they are still in great shape. I'm going to buy another pair. I think everyone should have a pair of these shoes in their closet.",
              "name": "Another Great Person",
              "rating": 4.5
            }
          ]
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The response now contains the 3 sample reviews that were included in Federate This.

## Commercetools remote source configuration

<Alert theme="warning" title="Prerequisite">
You need to have a <Link href="https://commercetools.com/" target="_blank">commercetools</Link> account as well as <Link href="https://docs.commercetools.com/learning-model-your-business-structure/organizations-and-projects/projects" target="_blank">have a project set up</Link>.
</Alert>

### Get your commercetools keys

Before we start, there is some data we will need from your commercetools account:

Go to **Settings > Developer settings > API clients**. Click `+ Create new API client` to create one from scratch, give it a name and select the scopes you need for your project.

In our example we will select the `Project` scope under **Manage**. Click `Create API client` at the top-right of the screen.

The resulting screen contains the information you will need to configure your remote source. Save it for later, and let's continue with the process.

### Commercetools Remote Source

![Commercetools Remote Source](/images/docs/user-guides/remote-sources/commercetools-remote-source.png)

Navigate to the schema builder and click `+Add` next to **Remote Sources**. Use the following information to configure your remote source:

| Field              | Input                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Remote source type | Select **Commercetools**                                                                                                                                                                                                                                     |
| Authorization URL  | This is the **Auth URL** in the API client details view of your commercetools account. Instead of copying it directly from there, copy the URL on the first line of the cURL below. Paste that in the Authorization URL field of your Hygraph Remote Source. |
| Scopes             | This is the **Scope** in the API client details view of your commercetools account. Copy it and paste it in Hygraph, then click `+ Add scope` to add.                                                                                                        |
| Client ID          | This is the **client_id** key in the API client details view of your commercetools account. Copy it and paste it in Hygraph. This is like a username.                                                                                                        |
| Client Secret      | This is the **secret** key in the API client details view of your commercetools account. Copy it and paste it in Hygraph. This is like a password.                                                                                                           |
| Display name       | This  is the display name of your Remote Source, we will write "Commercetools" here.                                                                                                                                                                         |
| Prefix             | Completing the display name autocompletes the prefix, you can leave it as is.                                                                                                                                                                                |
| Type               | Select `GraphQL`                                                                                                                                                                                                                                             |
| Base URL           | To form the base URL, you will use the **API URL** and the **project_key** from the API client details view of your commercetools account, like this: `https://<COMMERCETOOLS_API_URL>/<PROJECT_KEY>/graphql`.                                               |

Click `Add Remote Source` at the bottom of the screen to save your Remote Source.

## Commercelayer remote source configuration

<Alert theme="warning" title="Prerequisite">
You need to have a <Link href="https://dashboard.commercelayer.io/sign_up" target="_blank">Commercelayer</Link> account.
</Alert>

### Get your Commercelayer keys

Before we start, there is some data we will need from your Commercelayer account:

Go to **Applications > Add new**. Select a type, for this example we will select `Sales Channel`, give it a name, and click `Get credentials`.

The resulting screen contains the information you will need to configure your remote source. Save it and let's continue with the process.

### Commercelayer Remote Source

![Commercelayer Remote Source](/images/docs/user-guides/remote-sources/commercelayer-remote-source.png)

Navigate to the schema builder and click `+Add` next to **Remote Sources**. Use the following information to configure your remote source:

| Field              | Input                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remote source type | Select **Commercelayer**                                                                                                                                                            |
| Authorization URL  | Copy the **Base endpoint** in your Commercelayer credentials screen, paste it in Hygraph, and add `/oauth/token` at the end, like this: `https://<YOUR_BASE_ENDPOINT>/oauth/token`. |
| Scopes             | We won't add anything here for this example.                                                                                                                                        |
| Client ID          | Copy the **Client ID** in your Commercelayer credentials screen and paste it here.                                                                                                  |
| Client Secret      | We won't add anything here for this example.                                                                                                                                        |
| Display name       | This  is the display name of your Remote Source, we will write "Commercelayer" here.                                                                                                |
| Prefix             | Completing the display name autocompletes the prefix, you can leave it as is.                                                                                                       |
| Type               | Select `REST`                                                                                                                                                                       |
| Base URL           | Copy the **Base endpoint** in your Commercelayer credentials screen and paste it here.                                                                                              |

Click `Add Remote Source` at the bottom of the screen to save your Remote Source.

## Working with custom input types

In this example, we will see how we can define and use a custom input type on a Remote Field. We will be using the <Link href="https://docs.github.com/en/rest" target="_blank">Github REST API</Link>, specifically the `users` <Link href="https://docs.github.com/en/rest/reference/users#list-users" target="_blank">endpoint</Link>.

### Step 1: Configure Github as Remote Source

We'll first add the Github API as a Remote Source and configure the right custom (input) types.

Set up a new remote source. If you don't know how to do this, please [check out our documentation](/docs/developer-guides/remote-data/remote-sources), using `<Link href="https://api.github.com" target="_blank">https://api.github.com</Link>` as the base URL, then add a custom type with the following SDL:

```graphql
type User {
  avatar_url: String
  bio: String
  blog: String
  company: String
  created_at: DateTime
  email: String
  events_url: String
  followers: Int
  followers_url: String
  following: Int
  following_url: String
  gists_url: String
  gravatar_id: String
  hireable: Boolean
  html_url: String
  id: Int
  location: String
  login: String
  name: String
  node_id: String
  organizations_url: String
  public_gists: Int
  public_repos: Int
  received_events_url: String
  repos_url: String
  site_admin: Boolean
  starred_url: String
  subscriptions_url: String
  twitter_username: String
  type: String
  updated_at: DateTime
  url: String
}
```

Also add a custom _input_ type with the following SDL:

```graphql
input githubInput {
  userId: String!
}
```

### Step 2: Set up the Remote Field

In an appropriate model, set up a REST Remote Field. In this example, we will use a model called `Author` and set up the Remote Field with apiId `githubUserDetails`. In the Remote Field config, add an input argument and select the input type to be the previously created `githubInput`. In the example, we will use the auto-generated API ID `githubInput` for the input arguments. We'll also set the field to be required since we will make the path depend on the input value.

![Example - Input argument](/images/docs/user-guides/remote-sources/github-example-input-arg.png)

Now configure the Remote Field's path to use the input argument. You can use the autocomplete feature in the handlebars notation for this.

![Example - Remote Field path](/images/docs/user-guides/remote-sources/github-example-remote-field-path.png)

### Step 3: Query the field

Make sure there is at least one entry for the selected model, and then head over to the API Playground. The input argument can now be used in a query in the following way:

```graphql
query MyQuery {
  author(where: { id: "<some_id>" }) {
    id
    githubUserDetails(githubInput: { userId: "hygraph" }) {
      name
      bio
    }
  }
}
```

<Alert theme="info" title="Pro Tip">
Please note that since we've made the `userId` parameter required in the custom input type (by adding a `!` at the end), there will be an error if we don't supply the value properly.
</Alert>

## Fetching a product catalog

This example shows a product content entry that fetches the product catalog from a Remote Source.

Besides the data that lives in Hygraph inside a regular model called `Product` - Product name, product description, etc - you can fetch a product catalog from an external API through a remote source that you added to the `Product` model as a Remote Field.

![Remote Field example](/images/docs/user-guides/remote-sources/example-remote-field.png)

Requests will return information in Hygraph - `Product` model - as well as information in the Remote Source, called `myCatalogue` in our `Product` model for this example.

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  products {
    id
    myCatalogue {
      id
      name
      slug
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "products": [
      {
        "id": "clix9xjpu004n0btas02yx2ce",
        "myCatalogue": [
          {
            "id": "cl3jub4i9sl9o0eujar33f9rm",
            "name": "T Shirt",
            "slug": "t-shirt"
          },
          {
            "id": "cl3jub8gkslb90euj2n3ea357",
            "name": "Hoodie",
            "slug": "hoodie"
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The frontend could then use this information received through the Hygraph Content API to display the product page enriched with the product catalog.

## Add any REST source

This video tutorial covers adding a remote REST source into Hygraph.

<VideoEmbed videoId="NpHSqsol3xc" />

Tim shows us the two ways to query a REST remote source:

- Adding a global instance for the source, so we can query it from anywhere in our code.
- Using metadata to query from content editing in the CMS.

## Top-level Remote Fields

This example uses Top-level Remote Fields to show us a product information content entry that fetches the product catalogue from an external API, unrelated to Hygraph.

Besides the data that lives in Hygraph inside a regular model called **Product information** - `Slug`, `Title`, `Description` - you can fetch a product catalogue from an external API through a Remote Source that you add to the `Query` model as a Remote Field.

![Top-level Remote Field example](/images/docs/user-guides/remote-sources/example-top-level-remote-field.png)

Requests will return information in Hygraph - `Product` model- as well as information in the Remote Source, called `fieldremoteproduct` in our `Query` model for this example.

<Tabs panelHeight={270}>
  <TabsItem label="Query">

```graphql
{
  products {
    slug
    description
    title
  }
  fieldremoteproduct {
    slug
    name
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "products": [
      {
        "slug": "hoodie",
        "description": "Wrap yourself in cozy comfort with this stylish hoodie. Crafted from soft, premium materials, it offers a perfect blend of warmth and casual fashion. The versatile design features a kangaroo pocket for added convenience, while the adjustable drawstring hood adds an extra layer of coziness. Whether you're lounging at home or heading out for a casual outing, this hoodie is a must-have addition to your wardrobe.",
        "title": "Red Hoodie"
      }
    ],
    "fieldremoteproduct": [
      {
        "slug": "t-shirt",
        "name": "T Shirt"
      },
      {
        "slug": "hoodie",
        "name": "Hoodie"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The frontend could then use this information received through the Hygraph Content API to display the product page along with a product catalogue sourced from an external API.

## E-commerce platform

This video tutorial covers adding a remote source to Hygraph and creating Top-Level Remote Fields to pull in data from the external e-commerce platform, BigCommerce.

<VideoEmbed videoId="08vg5eYdsDc" />


---
# Remote Fields vs Top-level Remote Fields

Source: https://hygraph.com/docs/developer-guides/remote-data/remote-field

## Overview

Remote Fields are fields that you can add to a model in order to fetch data from a [remote source](/docs/developer-guides/remote-data/remote-sources). There are two types:

- **Remote Field:** A field inside a regular Hygraph model that connects specific remote data to an entry of that model. Remote Fields are always related to a single remote source and a single custom type. RESTful remote fields are configured with a path to a specific endpoint in the remote source, such as user details from Github, or price & availability from Shopify.
- **Top Level Remote Field:** A field inside the `Query` system model in Hygraph. These fields are used to fetch remote data outside the context of a regular model, which is then sent to your frontend alongside your Hygraph data. This [Content Federation](/docs/getting-started/fundamentals/content-federation) utility eliminates the need to make separate API requests for data inside & outside of Hygraph.

## Remote field types

You can use [Remote Fields](/docs/developer-guides/remote-data/remote-field#remote-fields) to enrich data by fetching information from a [Remote Source](/docs/developer-guides/remote-data/remote-sources). This data can be queried in the context of the model it's a part of.

[Top-level Remote Fields](/docs/developer-guides/remote-data/remote-field#top-level-remote-fields) fetch data that's unrelated to Hygraph and pass it through in the same API call as the data that is related to Hygraph content. This is what we'd call a [Content Federation](/docs/getting-started/fundamentals/content-federation) gateway case, where your frontend will receive everything as if coming from Hygraph, but the data itself can come from diverse sources.

### Remote Fields

![Remote Fields - Model view](/images/docs/user-guides/remote-sources/remote-fields-model-view.png)

Remote Fields are fields inside a Hygraph model that connect specific remote data to an entry of that model.

These fields are always related to a single Remote Source and a single custom type. RESTful Remote Fields are configured with a path to a specific endpoint in the Remote Source, such as user details from Github or price & availability from Shopify.

#### What you can do with Remote Fields

You can add Remote Fields to regular models in your schema to enrich data.

#### Possible use cases for Remote Fields

- They can facilitate e-commerce by consolidating product listings from multiple suppliers onto one platform.
- In travel, they can integrate flight, hotel, and rental car information from numerous providers.
- In stock management, they can provide real-time inventory data from various warehouses, enabling efficient tracking and management.


### Top-level Remote Fields

![Top-level Remote Fields - Query model](/images/docs/user-guides/remote-sources/top-level-remote-fields-query-model.png)

Top-level Remote Fields use the `Query` model, which is a custom resolver entry point for your schema that allows you to fetch remote data alongside the regular models in Hygraph.

You can find the Query model by navigating to the schema builder of your project.

These Top-level Remote Fields exist in their own model in the schema - the Query model - and you can use them to go beyond the content enrichment case by passing data that is unrelated to the content you have in your Hygraph project.

<Alert theme="info" title="Pro Tip">
We called this the `Query` model because in GraphQL query is the root type related to reading data.

This is also why adding Remote Fields to the `Query` model makes them available at the top level.
</Alert>

#### What you can do with Top-level Remote Fields

- You can use this model to pass data through our Content API without the need for it to be associated to a Hygraph content entry. In other words, you can use this model as a top-level entry point to fetch external data.
- Take advantage of our [Content Federation](/docs/getting-started/fundamentals/content-federation) capabilities by integrating more systems and using them independently from their Hygraph content.

#### Possible use cases for Top-level Remote Fields

- Data ownership needs to stay within the external system rather than being mirrored into another system.
- You are working with a multi-layered infrastructure where data enrichment happens before the data reaches Hygraph.
- Your website makes calls to APIs that are not related to Hygraph.
- You are working on a project where not all content entries need enrichment.



---
# Remote Source configuration

Source: https://hygraph.com/docs/developer-guides/remote-data/remote-sources

## Add a remote source

![Remote Sources - Select a type](/images/docs/user-guides/remote-sources/remote-source-select-type.png)

The first step to adding a remote source to your project is selecting the type. You can create a custom source or use a pre-built one. Hygraph offers pre-built remote sources for CommerceTools and CommerceLayer.

1. Navigate to the Schema Builder.
2. In the left sidebar, find the Remote Sources section at the bottom of the list, then click +Add.
3. Use the selection boxes at the top of the screen to select a remote source type:
        - Custom
        - CommerceTools
        - CommerceLayer

### Add a custom source

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvbajbs107w5ltraph9l" caption="Add custom Remote Source" />

After selecting a custom remote source, you can complete the following fields:

| Field                       | Input                                                                                                                                                                                                                                                                                                                                                                           |
|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Display Name`              | Enter a display name here. This name will appear in Hygraph.                                                                                                                                                                                                                                                                                                                    |
| `Prefix`                    | The prefix is auto-generated and will be added to all types that are created for this Remote Source to avoid name clashes.                                                                                                                                                                                                                                                      |
| `Description`               | You can optionally add a description of the Remote Source here.                                                                                                                                                                                                                                                                                                                 |
| `Enable debugging` checkbox | You can enable debugging for this Remote Source, which will provide more information in case of errors. **Make sure to disable this once you finish setting up the Remote Source to avoid leaking sensitive data**.                                                                                                                                                             |
| `Type`                      | Use the radio buttons to set the type to either `REST` or `GraphQL`, depending on the type of API that this remote source will connect to. More fields will display as a result of your selection. [Check out this document's “Select a type” section to learn more about configuring REST and GraphQL types](/docs/developer-guides/remote-data/remote-sources#select-a-type). |

### Add a commercetools source

<Alert theme="info" title="Are you looking for a full example?">
[Click here to view an example of how to configure a commercetools Remote Source](/docs/developer-guides/remote-data/remote-data-examples#commercetools-remote-source-configuration)
</Alert>

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xv9dhv3v07vx3qhunq11" caption="Add CommerceTools Remote Source" />

After selecting a CommerceTools Remote Source, you will find that the screen now contains two distinct sections for you to complete. The first section is the OAuth configuration for CommerceTools:

<div id="commercetools-scopes"></div>

| Field                 | Input                                                                                                                                                                                                                                |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Authorization URL** | Enter your CommerceTools authorization URL here. Copy the **Base endpoint** in your CommerceTools credentials screen, paste it in Hygraph, and add `/oauth/token` at the end, like this: `https://<YOUR_BASE_ENDPOINT>/oauth/token`. |
| **Scopes**            | Provide one or more scopes and click `+Add`. This is the **Scope** in the API client details view of your commercetools account. <Link href="https://docs.commercetools.com/api/scopes" target="_blank">Click here to learn more about Commercetools scopes</Link>.   |
| **Client ID**         | Enter your CommerceTools `Client ID` here. This is the **client_id** key in the API client details view of your commercetools account. Copy it and paste it in Hygraph. This is like a username.                                     |
| **Client Secret**     | Enter your CommerceTools `Client Secret` here. This is the **secret** key in the API client details view of your commercetools account. Copy it and paste it in Hygraph. This is like a password.                                    |

Once you've completed this, you can move on to the second section, where you will configure the details of your Remote Source:

| Field                         | Input                                                                                                                                                                                                                                                                                                                                                                           |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Display Name**              | Enter a display name here. This name will appear in Hygraph.                                                                                                                                                                                                                                                                                                                    |
| **Prefix**                    | The prefix is auto-generated and will be added to all types that are created for this Remote Source to avoid name clashes.                                                                                                                                                                                                                                                      |
| **Description**               | You can optionally add a description of the remote source here.                                                                                                                                                                                                                                                                                                                 |
| **Enable debugging** checkbox | You can enable debugging for this remote source, which will provide more information in case of errors. **Make sure to disable this once you finish setting up the Remote Source to avoid leaking sensitive data**.                                                                                                                                                             |
| **Type**                      | Use the radio buttons to set the type to either `REST` or `GraphQL`, depending on the type of API that this remote source will connect to. More fields will display as a result of your selection. [Check out this document's “Select a type” section to learn more about configuring REST and GraphQL types](/docs/developer-guides/remote-data/remote-sources#select-a-type). |

### Add a Commercelayer source

<Alert theme="info" title="Are you looking for a full example?">
[Click here to view an example of how to configure a Commercelayer Remote Source](/docs/developer-guides/remote-data/remote-data-examples#commercelayer-remote-source-configuration)
</Alert>

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xv78jbrt07w5dn43iv8h" caption="Add CommerceLayer Remote Source" />

After selecting a CommerceLayer remote source, you will find that the screen now contains two distinct sections for you to complete. The first section is the OAuth configuration for CommerceLayer:

<div id="commercelayer-scopes"></div>

| Field                 | Input                                                                                                                                                                                                                                |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Authorization URL** | Enter your CommerceLayer authorization URL here. Copy the **Base endpoint** in your Commercelayer credentials screen, paste it in Hygraph, and add `/oauth/token` at the end, like this: `https://<YOUR_BASE_ENDPOINT>/oauth/token`. |
| **Scopes**            | Provide one or more scopes and click `+Add`. This field is optional. <Link href="https://docs.commercelayer.io/core/authentication#authorization-scopes" target="_blank">Click here to learn more about Commercelayer scopes</Link>.                                  |
| **Client ID**         | Enter your CommerceLayer `Client ID` here. Copy the **Client ID** in your Commercelayer credentials screen and paste it here.                                                                                                        |
| **Client Secret**     | You can optionally enter your CommerceLayer `Client Secret` here. This field is optional.                                                                                                                                            |

Once you've completed this, you can move on to the second section, where you will configure the details of your Remote Source:

| Field                         | Input                                                                                                                                                                                                                                                                                                                                                                           |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Display Name**              | Enter a display name here. This name will appear in Hygraph.                                                                                                                                                                                                                                                                                                                    |
| **Prefix**                    | The prefix is auto-generated and will be added to all types that are created for this Remote Source to avoid name clashes.                                                                                                                                                                                                                                                      |
| **Description**               | You can optionally add a description of the remote source here.                                                                                                                                                                                                                                                                                                                 |
| **Enable debugging** checkbox | You can enable debugging for this remote source, which will provide more information in case of errors. **Make sure to disable this once you finish setting up the Remote Source to avoid leaking sensitive data**.                                                                                                                                                             |
| **Type**                      | Use the radio buttons to set the type to either `REST` or `GraphQL`, depending on the type of API that this remote source will connect to. More fields will display as a result of your selection. [Check out this document's “Select a type” section to learn more about configuring REST and GraphQL types](/docs/developer-guides/remote-data/remote-sources#select-a-type). |

## Select a type

### REST

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvfihv4d07vxluglw51b" caption="Remote Source - REST" />

The following fields display when you select the `REST` type:

| Field                       | Input                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Base URL**                | Enter a base URL here. All Remote Fields that connect to this Remote Source will use that base URL. <br></br>**Commercetools Base URL:** To form the base URL, you will use the **API URL** and the **project_key** from the API client details view of your commercetools account, like this: `https://<COMMERCETOOLS_API_URL>/<PROJECT_KEY>/graphql`. <br></br> **Commercelayer Base URL:** Copy the **Base endpoint** in your Commercelayer credentials screen and paste it here. |
| **Headers**                 | Optionally, you can include HTTP headers that will be added to all API requests for all Remote Fields connected to this Remote Source. Example use cases include authorization and accepted media types.                                                                                                                                                                                                                                                                             |
| **Custom type definitions** | You can now [define your custom types](/docs/developer-guides/remote-data/remote-sources#create-a-custom-type-definition) here. These provide the mapping from the API responses to the GraphQL schema. [Custom input types](/docs/developer-guides/remote-data/remote-sources#create-a-custom-input-type-definition) can optionally also be defined here.                                                                                                                           |

### GraphQL

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvdjhv4507vxhy5hkgxs" caption="Remote Source - GraphQL" />

The following fields display when you select the `GraphQL` type:

| Field                            | Input                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Base URL**                     | Enter a base URL here. All Remote Fields that connect to this Remote Source will use that base URL. <br></br>**Commercetools Base URL:** To form the base URL, you will use the **API URL** and the **project_key** from the API client details view of your commercetools account, like this: `https://<COMMERCETOOLS_API_URL>/<PROJECT_KEY>/graphql`. <br></br> **Commercelayer Base URL:** Copy the **Base endpoint** in your Commercelayer credentials screen and paste it here. |
| **Headers**                      | Optionally, you can include HTTP headers that will be added to all API requests for all Remote Fields connected to this Remote Source. Example use cases include authorization and accepted media types.                                                                                                                                                                                                                                                                             |
| **Custom input type definition** | You can optionally provide an alternative introspection URL and custom headers to send to the introspection endpoint. If no separate introspection URL is provided, the base URL will be used (the default behavior for most GraphQL APIs is to allow querying and introspection on the same URL). [Custom input types](/docs/developer-guides/remote-data/remote-sources#create-a-custom-input-type-definition) can optionally also be defined here.                                |
| **Introspection method**         | Select `GET` or `POST`. <br></br>If `GET`, we do a `GET` request and include the introspection query in the URL as a query parameter.<br></br>If `POST`, we do a `POST` request and include the introspection query in the body.                                                                                                                                                                                                                                                     |
| **Introspection URL**            | If your introspection URL is different from the Remote Source URL, you can add it here.                                                                                                                                                                                                                                                                                                                                                                                              |
| **Introspection headers**        | Here, you can add the headers to pass along with the request to the remote source.<br></br>Simply add a key and value pair and click `+ Add header`.                                                                                                                                                                                                                                                                                                                                 |

## Create a custom type definition

When connecting to a remote `REST API`, you will have the option to define a **Custom Type Definition**, which allows you to specify the shape of the response coming from the API. It will allow you to query the `REST API` as if it were native `GraphQL`.

These **Custom Type Definitions** use `GraphQL SDL` (Schema Definition Language).

<Alert theme="info" title="Pro Tip">

A `Schema Definition Language` or `SDL` is a way to define the shape of data that can be queried in a `GraphQL API`. It describes the schema or types of data available, their relationships, and how the data can be queried. We need to tell Hygraph the shape of the data to expect and make available.

While a `REST API` can use multiple endpoints to return fixed data structures, a `GraphQL API` - not being limited to returning fixed structures - will expose just one. The custom type definitions that we add in this step allow us to specify the shape of the response coming from the API, so we can query the `REST API` as if it were native `GraphQL`.

<Link href="https://www.howtographql.com/basics/2-core-concepts" target="_blank">Click here to learn more about GraphQL SDL</Link>
</Alert>

Follow these steps to create a custom type definition:

1. While [adding a new Remote Source](/docs/developer-guides/remote-data/remote-sources#add-a-remote-source) or editing an existing one, scroll down to `Custom Type Definitions` and click `+Add`.
2. You can use our <Link href="https://hygraph-json-to-sdl.vercel.app/" target="_blank">JSON to SDL converter tool</Link> to transform the `JSON` response from your API into valid `GraphQL SDL`. You might need to make a few tweaks to the generated SDL, especially changing the `JSON` type to `Json` (note the difference in casing).

    Here's an example of what that would look like:

    <Tabs panelHeight={240}>

    <TabsItem label="JSON">

    ```json
    {
      "login": "name",
      "id": 9197688,
      "url": "https://api.github.com/users/name",
      "repos_url": "https://api.github.com/users/name/repos",
      "name": "John Doe",
      "company": "@ACME",
      "email": "mail@example.com"
    }
    ```

    </TabsItem>

    <TabsItem label="SDL">

    ```graphql
    type GithubUser {
      company: String
      email: String
      id: Int
      login: String
      name: String
      repos_url: String
      url: String
    }
    ```

    </TabsItem>

    </Tabs>

4. Add the SDL for your custom type to the input field. It's possible to add multiple types in a single input field, after saving the types will be moved to separate fields.

5. Click `Create` or `Save` on the top right corner.

Custom types also support nesting, so they can make use of another type, as shown below:

```graphql
type Product {
  name: String
  metaInfo: MetaInfo
  slug: String
}
```

```graphql
type MetaInfo {
  createdAt: DateTime
  createdBy: String
  currency: String
}
```

In this example, the custom `Product` type makes use of another custom type `MetaInfo`.

## Create a custom input type definition

Remote Fields also allow you to pass along input parameters to your Remote Source endpoint. This can be useful if the identifiable information for the remote data isn't kept in Hygraph, but defined on a request basis. This is relevant for both the `REST` and GraphQL Remote Sources.

To create such a definition and to use it in a query, you will need to follow these steps:

1.  While [adding a new Remote Source](/docs/developer-guides/remote-data/remote-sources#add-a-remote-source), or editing an existing one, scroll down to `Custom Input Type Definition` and click on `+Add`.
2.  Similar to the Custom Types, you need to use the GraphQL Schema Definition Language (SDL) to define what the input parameter will look like. A tool that could be used here is <Link href="https://www.json2sdl.com/" target="_blank">JSON2SDL</Link>, which allows translating a `JSON` object to a valid SDL. Keep in mind that we are not defining a <Link href="https://graphql.org/learn/schema/#object-types-and-fields" target="_blank">type</Link> here, but an <Link href="https://graphql.org/learn/schema/#input-types" target="_blank">input</Link>.

    Let's take an example of passing a `productId` to our remote API, that will be used as an input argument. The SDL would look like this:

    ```graphql
    input productInput {
      productId: String!
    }
    ```

---
# Remote data troubleshooting

Source: https://hygraph.com/docs/developer-guides/remote-data/troubleshooting

## Known issues and tips

If you work with Remote Sources and you query a lot of entries at the same time, make sure to use sensible pagination limits within Hygraph, so requests to a third-party API are not rate limited or blocked.

When defining a custom type, you can use all the default <Link href="https://graphql.org/learn/schema/" target="_blank">GraphQL Scalars</Link> such as String, Int, Float, Boolean, ID and additionally Json. `!` can be used to indicate a field not being nullable, `[Type]` will indicate a <Link href="https://graphql.org/learn/schema/" target="_blank">list</Link> (array). More info on the object types and fields can be found here: <Link href="https://graphql.org/learn/schema/" target="_blank">https://graphql.org/learn/schema/</Link>

## Refreshing a GraphQL Remote Source

If something changes on your GraphQL API - i.e., adding or removing fields, or changing types - you can refresh the Remote Source.

![Refetch remote schema](/images/docs/user-guides/remote-sources/refetch-remote-schema.png)

To do this, navigate to the GraphQL Remote Source you want to refresh, click on the context menu, then click on `Refetch Remote Schema`.

This sends the new introspection query through the API, and once it goes through successfully, you can use the new fields.

<Alert theme="warning">
If there is an error happening on refetching, please check the `Query` section of your Remote Source configuration screen. Make sure that your remote fields are not using a type that's been updated or removed, and that the return type is not using it either.

[Our documentation on **Adding remote data to your model**](/docs/developer-guides/remote-data/remote-content) covers introspection queries.

This issue can be avoided by working on additive changes.
</Alert>

## Error querying remote fields

Irrespective of the model you selected, the default behavior for errors in querying Remote Fields is that the query to Hygraph will return successfully but with a `null` value for the Remote Field and an error message to indicate the Remote Field could not be queried. If the value of the Remote Field is critical for the proper functioning of the front-end application, it's possible to mark the Remote Field as `required`. With this setting enabled, the whole query to Hygraph will return an error if the Remote Field does not provide a successful response.

![Error querying remote fields](/images/docs/user-guides/remote-sources/remote-field-required-option.png)



---
# Click to Edit setup

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit

Click to Edit lets editors jump from any tagged element in a content preview directly to that field in Hygraph Studio. You configure it on the frontend using the <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Hygraph Preview SDK</Link>. Editors perform the following steps without any further developer involvement:
1. Hover over a tagged element in preview to display an **Edit** button.
2. Click the **Edit** button to open the corresponding field entry in Studio.
3. Save changes to automatically refresh the preview.

<Alert theme="info">
Click to Edit is built on top of live preview. You do not need live preview running before you start, but editors get the full visual editing experience only when both are set up. See [live preview setup](/docs/developer-guides/schema/live-preview) if you have not configured it yet.
</Alert>

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmirlamtb1vpz06w6c76kn30k" caption="Click to Edit in content preview" />

## How it works

The SDK operates in two modes that are automatically detected:
  - **Iframe Mode**: When your preview loads in an iframe inside Hygraph Studio.
  - **Standalone Mode**: When your preview loads in a separate browser tab outside Studio.

In both modes, the SDK scans your rendered HTML for `data-hygraph-*` attributes. These attributes map each element back to a specific entry and field in Hygraph. The SDK adds hover overlays and **Edit** buttons automatically. When an editor saves in Studio, Hygraph sends a save event to the preview so it can refresh while preserving scroll position.

Real-time field updates are disabled by default. The preview refreshes on save only. You can enable live updates with `sync={{ fieldUpdate: true }}`.

## Get started

### Availability

- The Click to Edit feature is available for all projects and is currently in Beta.

### Prerequisites

- A Hygraph project with at least one model and content entry.
- A running preview application (local or deployed) using React, Next.js, Remix, Vue, or vanilla JavaScript.

### Setup steps

1. [Install the Preview SDK](#install-the-preview-sdk).
2. [Create a PreviewWrapper component to enable the preview functionality](#create-the-previewwrapper-component).
3. [Set environment variables](#set-environment-variables).
4. [Add data attributes to content elements](#add-data-attributes-to-content-elements).
5. [Set up the Preview widget in Studio](#set-up-the-preview-widget-in-studio).
6. [Verify the setup](#verify-the-setup).

## Install the Preview SDK

The SDK connects your frontend to Studio. It handles overlay rendering, save event listening, and iframe/standalone mode detection.

```bash
npm install @hygraph/preview-sdk
```

## Create the PreviewWrapper component

The `PreviewWrapper` component initializes the SDK across your application, and enables the preview functionality. Choose the implementation that matches your framework:
- [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router#create-the-previewwrapper-component)
- [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router#create-the-previewwrapper-component)
- [Remix](/docs/developer-guides/schema/click-to-edit-remix#create-the-previewwrapper-component)
- [Vue](/docs/developer-guides/schema/click-to-edit-vue-nuxt#vue)
- [Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt#nuxt)
- [Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js)

### Configuration properties

| Property | Required | Description |
|---|---|---|
| `endpoint` | Required | Your Hygraph Content API endpoint. See [Content API](/docs/developer-guides/project/api-access#content-api). |
| `studioUrl` | Optional (recommended) | Studio base URL. Defaults to `https://app.hygraph.com`. Set this if your Studio runs on a regional or custom domain. |
| `onSave` | Optional | Callback fired after Studio reports a save. Receives the saved entry ID. Use this to trigger revalidation or a router refresh. |
| `debug` | Optional | Enables verbose console logging. Useful for diagnosing missing attribute issues. |
| `mode` | Optional | Forces `'iframe'`, `'standalone'`, or `'auto'`. Auto-detection works for most cases. |
| `overlay` | Optional | Customize overlay border color, border width, button background, and button text color. |
| `sync.fieldFocus` | Optional | Synchronizes field focus between Studio and the preview when an editor selects a field. |
| `sync.fieldUpdate` | Optional | Applies live field changes to the preview as the editor types. Defaults to `false`. |
| `allowedOrigins` | Optional | Additional domains that can host the preview iframe, such as staging or QA environments. |

## Set environment variables

Set the following values in `.env.local`. If you already configured these for live preview, skip this step.

```bash
NEXT_PUBLIC_HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
NEXT_PUBLIC_HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token
```

- **Content API endpoint**: Copy your Content API endpoint from your Hygraph project settings under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our dedicated docs on the [Content API](/docs/developer-guides/project/api-access#content-api).
- **Hygraph Studio base URL**: Copy the base Studio URL from your browser's address bar. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.
- **Permanent Auth Token**: You can create a Permanent Auth Token under **Project Settings > Access > Permanent Auth Tokens**. Check that the default content stage is DRAFT. For more information, see our dedicated docs on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).
    - This is needed only if your Hygraph project requires authentication for Content API requests.

## Add data attributes to content elements

The SDK uses `data-hygraph-*` attributes to map rendered elements back to Hygraph fields. Add them to the JSX or HTML elements that render Hygraph content. You do not need to instrument every element; add attributes only to the fields editors need to edit from the preview.

The SDK scans rendered HTML for these attributes and attaches hover overlays and **Edit** buttons automatically. The same attributes work for variants. When an editor opens a variant, clicking a tagged element focuses the corresponding field directly in the variant overlay.

| Attribute | Required | Description |
|---|---|---|
| `data-hygraph-entry-id` | Required | The content entry ID. Every editable element needs this. Always use the root entry ID, not a component instance ID. |
| `data-hygraph-field-api-id` | Optional | The API ID of the field in the schema. Without this, clicking **Edit** opens the entry without focusing a specific field. |
| `data-hygraph-rich-text-format` | Optional | Format for Rich Text fields. Accepts `html`, `markdown`, or `text`. |
| `data-hygraph-component-chain` | Optional | JSON array describing the path to a nested component field. See [tagging component fields](#tagging-component-fields). |

![`data-hygraph-entry-id` - Content entry](/images/docs/developer-guides/click-to-edit-data-attributes-simple.png)

To find the `data-hygraph-field-api-id`:

1. Open **Schema** and select your model.
2. Locate the field. The API ID appears next to the field name in camelCase without any spaces.
3. Use that value as `data-hygraph-field-api-id`.

![`data-hygraph-field-api-id` - Schema](/images/docs/developer-guides/click-to-edit-data-attributes-api-id.png)

### Tagging component fields

Components require the `data-hygraph-component-chain` attribute in addition to the standard attributes. This tells Studio how to navigate from the root entry to the specific nested component instance.

The chain is a JSON array of `{ fieldApiId, instanceId }` objects ordered from outermost to innermost component. The `instanceId` is the unique identifier of the component instance returned in your GraphQL response. It is not the component type's API ID, and it does not appear in the Studio UI.

<Alert theme="info">
You do not copy instance IDs from Studio. Query for the `id` field on each component in your GraphQL query. The SDK reads this value from your data at render time to build the chain.
</Alert>

| Attribute | Description |
|---|---|
| `data-hygraph-entry-id` | The root content entry ID. Never use a component's own ID here. |
| `data-hygraph-field-api-id` | The API ID of the specific field inside the component. Identifies which field to focus within the entry in the editor. Without it, the edit button opens the entry unfocused. |
| `data-hygraph-component-chain` | JSON array of `{ fieldApiId, instanceId }` describing the path from root entry to the target field. <ul><li><code>fieldApiId</code> - The field that contains the nested component. </li><li><code>instanceId</code> - Unique identifier of the component instance, as returned in your GraphQL query as described below. This is not the API ID of the component. </li></ul> |

![Data attributes components markup](/images/docs/developer-guides/click-to-edit-data-attributes-components.png)

#### Query to retrieve instanceId

Retrieve the `instanceId` using the following query:

<Tabs>
  <TabsItem label="Query to retrieve instanceId">
```graphql
query MyQuery {
  recipes(where: {id: "<your_recipe_ID>"}) {
    __typename
    id # This is the entry ID
    nutrition {
      id # This is the instanceId for the component chain
    }
    ingredients {
      id # This is the instanceId for the component chain
    }
    featuredContent {
      ... on IngredientSpotlight {
        id # This is the instanceId for the component chain
      }
    }
    additionalSections {
      ... on ProTip {
        id # This is the instanceId for the component chain
      ... on VideoEmbed {
        id # This is the instanceId for the component chain
      }
    }
  }
}
}
```

  </TabsItem>
  <TabsItem label="Response with instanceId">

```json
{
  "data": {
    "recipes": [
      {
        "__typename": "Recipe",
        "id": "cmionbkxj01jm07vpwefnyv1b",
        "nutrition": {
          "id": "cmionbkxx01jz07vpqfq1fqu1"
        },
        "ingredients": [
          {
            "id": "cmionbkxw01jn07vplxi3igp7"
          },
          {
            "id": "cmionbkxw01jp07vpq225ziap"
          },
          {
            "id": "cmionbkxx01jr07vp3a7qgx9o"
          },
          {
            "id": "cmionbkxx01jt07vp26pn1h1s"
          },
          {
            "id": "cmionbkxx01jv07vpcqagyg5b"
          },
          {
            "id": "cmionbkxx01jx07vpscvzswph"
          }
        ],
        "featuredContent": {
          "id": "cmiq3y64i0cn207vpxxinofiv"
        },
        "additionalSections": [
          {
            "id": "cmiq3y64s0cn607vp4zlz0q5y"
          },
          {
            "id": "cmiq3y64s0cn407vpv509s5jq"
          }
        ]
      }
    ]
  }
}
```
  </TabsItem>
</Tabs>

## Set up the Preview widget in Studio

If you have already configured a Preview widget for [live preview](/docs/developer-guides/schema/live-preview), you can skip this step. Click to Edit uses the same widget.

1. Open your Hygraph project.
2. Navigate to **Schema** and select your model.
3. Click the **Sidebar** tab.
4. Select the **Preview** widget from the right sidebar.
5. Complete the **Preview name** and the **URL template** fields, and click **Add**.

## Verify the setup

After completing all setup steps, confirm Click to Edit is working end to end.

1. Open an entry in Studio for the model you configured live preview.
2. In the right sidebar, under **Preview**, click **Open live preview**. The preview should load alongside the entry form.
3. Hover over an element you tagged with `data-hygraph-*` attributes. An **Edit** button should appear.
4. Click **Edit**. Studio should scroll to and focus the corresponding field in the entry form.
5. Edit the field value and click **Save & Preview**. The preview should refresh and show the updated content.

If the **Edit** button does not appear at step 3, add `debug={true}` to your `PreviewWrapper` component and check the browser console for attribute warnings. Common causes are listed in [Troubleshooting](#troubleshooting) below.

## Known limitation

Click to Edit cannot navigate to a field in a specific locale. The **Edit** button opens the correct field in the default locale, but the editor needs to select the field for the target locale manually within Studio.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmowrrfomdqyh07upz2em2pl0" caption="Click to Edit - Localized fields" />

## Troubleshooting

### Edit buttons do not appear

- Confirm `data-hygraph-entry-id` is present on the element.
- Add `debug={true}` to your `PreviewWrapper` component and check the browser console.
- Verify `NEXT_PUBLIC_HYGRAPH_ENDPOINT` is set correctly.

### Preview does not open

Vercel sets an `X-Frame-Options` response header that blocks iframe loading. In your Vercel project, go to **Settings > Deployment Protection** and disable **Vercel Authentication**.

### Preview does not refresh after saving

- Confirm the `onSave` callback calls your framework's refresh method, for example, `router.refresh()` in Next.js.
- Verify your Permanent Auth Token has **DRAFT** set as the default content stage.
- Confirm your GraphQL queries request the `DRAFT` stage in preview mode.

### Real-time field updates not working

Real-time updates are disabled by default. Add `sync={{ fieldUpdate: true }}` to your `PreviewWrapper` component to enable them.

### Components do not focus correctly

- Check that `data-hygraph-entry-id` is always the root entry ID, not the component instance ID.
- Verify the `instanceId` values in your component chain match the `id` fields returned by your GraphQL query.
- Confirm the component chain array is ordered from outermost to innermost component.

## What's next

- [Click to Edit - Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router): Complete implementation for Next.js App Router with code examples for simple fields, basic, nested, and modular components.
- [Click to Edit - Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router): Complete implementation for Next.js Pages Router with code examples for simple fields, basic, nested, and modular components.
- [Click to Edit - Remix](/docs/developer-guides/schema/click-to-edit-remix): Complete implementation for Remix with code examples for simple fields, basic, nested, and modular components.
- [Click to Edit - Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt): Complete implementation for Vue and Nuxt, with shared attribute examples for simple fields, basic, nested, and modular components.
- [Click to Edit - Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js): Complete implementation for vanilla JavaScript with code examples for simple fields, basic, nested, and modular components.
- [Click to Edit - Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api): React hooks, Preview methods, DOM events, and helpers for dynamic content.

---
# Click to Edit - Advanced API

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit-advanced-api

This page covers advanced Preview SDK APIs beyond the standard [Click to Edit setup](/docs/developer-guides/schema/click-to-edit). Use it when you need custom save handling, connection status, dynamic DOM updates, or lower-level control than `PreviewWrapper` provides.

For framework walkthroughs, see:
- [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router)
- [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router)
- [Remix](/docs/developer-guides/schema/click-to-edit-remix)
- [Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt)
- [Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js)

## Additional configuration

These options extend the [configuration properties](/docs/developer-guides/schema/click-to-edit#configuration-properties) on the parent setup page.

| Property | Required | Description |
|---|---|---|
| `overlayEnabled` | Optional | Set to `false` to disable hover overlays and **Edit** buttons while keeping the Studio connection active. Defaults to `true`. Available on both `HygraphPreview` and the core `Preview` constructor. |

```tsx
<HygraphPreview
  endpoint={process.env.NEXT_PUBLIC_HYGRAPH_ENDPOINT!}
  studioUrl={process.env.NEXT_PUBLIC_HYGRAPH_STUDIO_URL}
  overlayEnabled={false}
  onSave={() => router.refresh()}
>
  {children}
</HygraphPreview>
```

## React hooks

Import hooks from `@hygraph/preview-sdk/react`. They must run inside a tree wrapped by `HygraphPreview`.

### `usePreview`

Returns the Preview instance and connection state.

```tsx
import { usePreview } from '@hygraph/preview-sdk/react';

function PreviewStatus() {
  const { preview, isReady, isConnected } = usePreview();

  return (
    <p>
      Ready: {String(isReady)} · Connected: {String(isConnected)} · Mode:{' '}
      {preview?.getMode() ?? 'n/a'}
    </p>
  );
}
```

### `usePreviewSave`

Subscribes to save events. Use this instead of (or in addition to) the `onSave` prop when save handling lives in a child component.

```tsx
import { usePreviewSave } from '@hygraph/preview-sdk/react';
import { useRouter } from 'next/navigation';

function SaveListener() {
  const router = useRouter();

  usePreviewSave((entryId) => {
    console.log('Saved entry:', entryId);
    router.refresh();
  });

  return null;
}
```

### `usePreviewEvent`

Subscribes to any [DOM event](#dom-events) the SDK dispatches on `document`.

```tsx
import { usePreviewEvent } from '@hygraph/preview-sdk/react';

function FieldClickListener() {
  usePreviewEvent('preview:field-click', (event) => {
    console.log('Field clicked:', event.detail);
  });

  return null;
}
```

### Other React hooks

| Hook | Description |
|---|---|
| `usePreviewRefresh` | Returns a framework-aware `refresh()` helper. Falls back to `window.location.reload()` when no framework integration is detected. |
| `usePreviewRemix` | Subscribes to save events and revalidates with the Remix revalidator when available. |
| `usePreviewFieldUpdates` | Callbacks for `preview:field-updated` and `preview:update-failed` when `sync.fieldUpdate` is enabled. |
| `usePreviewConnection` | Returns `{ isConnected, isReady, mode }`. |
| `usePreviewActions` | Returns `{ refresh, destroy, getVersion, getMode }` for manual control. |
| `usePreviewDebug` | Returns registry stats and framework detection for development. |

### `HygraphPreviewNextjs`

Optional Next.js helper that wires `refresh` for you. Most apps use `HygraphPreview` with `next/dynamic` and `onSave={() => router.refresh()}` instead, as shown in the [App Router guide](/docs/developer-guides/schema/click-to-edit-next-js-app-router).

```tsx
import { HygraphPreviewNextjs } from '@hygraph/preview-sdk/react';
import { useRouter } from 'next/navigation';

export function PreviewWrapper({ children }: { children: React.ReactNode }) {
  const router = useRouter();

  return (
    <HygraphPreviewNextjs
      endpoint={process.env.NEXT_PUBLIC_HYGRAPH_ENDPOINT!}
      studioUrl={process.env.NEXT_PUBLIC_HYGRAPH_STUDIO_URL}
      refresh={router.refresh}
    >
      {children}
    </HygraphPreviewNextjs>
  );
}
```

## Core `Preview` methods

When you initialize the SDK with `new Preview()` (vanilla JavaScript, Vue, Nuxt), use these methods on the instance.

| Method | Description |
|---|---|
| `subscribe('save', { callback })` | Listens for Studio save events. Returns an unsubscribe function. |
| `refresh()` | Re-scans the DOM for `data-hygraph-*` attributes. Call after you inject or replace HTML without a full page reload. |
| `getMode()` | Returns `'iframe'` or `'standalone'`. |
| `isConnected()` | Returns whether the SDK is connected to Studio. |
| `getVersion()` | Returns the SDK version string. |
| `configureOverlay(config)` | Updates overlay styles at runtime. |
| `destroy()` | Tears down listeners, overlays, and the Studio connection. Call on page unload in SPAs. |
| `getFrameworkIntegration()` | Returns the SDK's framework integration helper used for framework-aware refresh. |
| `getFieldRegistryStats()` | Returns counts and diagnostics for registered preview fields. Useful when debugging missing overlays. |
| `getFieldRegistryKeys()` | Returns the registry keys for currently tracked fields. |

```js
import { Preview } from '@hygraph/preview-sdk/core';

const preview = new Preview({
  endpoint: process.env.HYGRAPH_ENDPOINT,
  studioUrl: process.env.HYGRAPH_STUDIO_URL,
  debug: true,
});

const unsubscribe = preview.subscribe('save', {
  callback: (entryId) => {
    console.log('Saved:', entryId);
    window.location.reload();
  },
});

window.addEventListener('beforeunload', () => {
  unsubscribe();
  preview.destroy();
});
```

### Dynamic content without a full reload

If your app updates the DOM without navigating away, call `refresh()` after new marked-up HTML is in the page:

```js
container.innerHTML = `
  <h1
    data-hygraph-entry-id="${entry.id}"
    data-hygraph-field-api-id="title"
  >
    ${entry.title}
  </h1>
`;

preview.refresh();
```

## Live preview for component arrays

When `sync.fieldUpdate` is enabled, the SDK can update component arrays (modular content) in the preview without a full page refresh:

- **Reordering** (drag-and-drop) — existing DOM elements move in place
- **Deletion** — removed components disappear immediately
- **Addition** — new unsaved components are skipped until you save and refresh the page

### Set up a component array container

The SDK needs:

1. A **container element** with `data-hygraph-entry-id` and `data-hygraph-field-api-id` pointing to the component array field
2. **Direct children** with `data-hygraph-component-chain` so the SDK can identify each component instance

```tsx
import {
  createPreviewAttributes,
  createComponentChainLink,
} from '@hygraph/preview-sdk/core';

function ArticlePage({ article }) {
  return (
    <main>
      <h1 {...createPreviewAttributes({ entryId: article.id, fieldApiId: 'title' })}>
        {article.title}
      </h1>

      {/* Container — the SDK targets this for reordering */}
      <div
        {...createPreviewAttributes({
          entryId: article.id,
          fieldApiId: 'content', // Must match the component array field API ID
        })}
      >
        {article.content.map((block) => {
          const componentChain = [createComponentChainLink('content', block.id)];

          return (
            <div
              key={block.id}
              data-hygraph-component-chain={JSON.stringify(componentChain)}
            >
              <ContentBlock
                block={block}
                articleId={article.id}
                componentChain={componentChain}
              />
            </div>
          );
        })}
      </div>
    </main>
  );
}
```

### How it works

When Studio detects a structural change (reorder, add, or delete) in a component array, it sends a `COMPONENT_ARRAY` field update. The SDK then:

1. Finds the container via `data-hygraph-entry-id` and `data-hygraph-field-api-id`
2. Reads `data-hygraph-component-chain` from each direct child to map component IDs to DOM elements
3. Reorders existing DOM elements to match the new array order
4. Removes elements for deletions
5. Skips new unsaved components until save and refresh

For Rich Text fields rendered as HTML inside components, add `data-hygraph-rich-text-format="html"` so live field updates use the correct format.

### Troubleshooting component arrays

- Confirm the **container** has `data-hygraph-entry-id` and `data-hygraph-field-api-id` matching the component array field.
- Confirm each direct child has `data-hygraph-component-chain` with the component instance ID.
- Enable `debug={true}` (or `debug: true`) to see `[ContentUpdater] COMPONENT_ARRAY` logs.
- New unsaved components appear only after saving and refreshing. Reordering and deletion of existing components work immediately when `sync.fieldUpdate` is enabled.

## DOM events

The SDK dispatches these events on `document`. Listen with `addEventListener` or `usePreviewEvent`.

| Event | `event.detail` | When it fires |
|---|---|---|
| `preview:ready` | `{ preview }` | SDK finished initializing. |
| `preview:connected` | `{ studioOrigin }` | Connected to Studio in iframe mode. |
| `preview:disconnected` | `{}` | Connection to Studio ended. |
| `preview:content-saved` | `{ entryId, timestamp }` | Studio reported a save. |
| `preview:field-click` | `{ entryId, fieldApiId?, locale?, componentChain?, mode? }` | Editor clicked an **Edit** overlay. |
| `preview:field-focus` | `{ entryId, fieldApiId, locale? }` | Studio requested field focus sync. |
| `preview:field-updated` | `{ entryId, fieldApiId, newValue }` | A live field update applied (`sync.fieldUpdate: true`). |
| `preview:update-failed` | `{ entryId, fieldApiId, error }` | A live field update failed. |

```js
document.addEventListener('preview:ready', () => {
  console.log('Preview SDK ready');
});

document.addEventListener('preview:content-saved', (event) => {
  console.log('Content saved:', event.detail.entryId);
});

document.addEventListener('preview:field-click', (event) => {
  console.log('Field clicked:', event.detail);
});
```

## Attribute helpers

These helpers from `@hygraph/preview-sdk/core` are used throughout the framework guides. The parent [attribute reference](/docs/developer-guides/schema/click-to-edit#add-data-attributes-to-content-elements) covers the HTML attributes they produce.

| Helper | Description |
|---|---|
| `createPreviewAttributes({ entryId, fieldApiId?, locale?, componentChain? })` | Returns an object of `data-hygraph-*` attributes for JSX or `v-bind`. |
| `createComponentChainLink(fieldApiId, instanceId)` | Builds one `{ fieldApiId, instanceId }` link for nested components. |
| `withFieldPath(attributes, fieldPath)` | Adds `data-hygraph-field-path` (for example, `ingredients.0.quantity`) for debugging nested fields. It does not change Studio focus behavior. |

```tsx
import {
  createPreviewAttributes,
  createComponentChainLink,
  withFieldPath,
} from '@hygraph/preview-sdk/core';

const chain = [createComponentChainLink('ingredients', ingredient.id)];

const quantityAttributes = withFieldPath(
  createPreviewAttributes({
    entryId: recipe.id,
    fieldApiId: 'quantity',
    componentChain: chain,
  }),
  `ingredients.${index}.quantity`
);
```

`createPreviewAttributes` also accepts an optional `locale`, which sets `data-hygraph-field-locale`. Click to Edit still cannot jump to a non-default locale in Studio; see the [known limitation](/docs/developer-guides/schema/click-to-edit#known-limitation).

## What's next

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): Install steps, attribute reference, Studio widget, and troubleshooting.
- [Click to Edit - Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js): UMD setup and server-rendered attribute examples.
- <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Preview SDK on GitHub</Link>: Source, changelog, and runnable examples.


---
# Click to Edit - Next.js App Router

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit-next-js-app-router

This page walks through implementing Click to Edit in a Next.js App Router project using the [Hygraph Preview SDK](https://github.com/hygraph/preview-sdk). By the end, editors can click any instrumented element in the preview to jump directly to that field in Studio.

For the general setup overview and configuration reference, see [Click to Edit setup](/docs/developer-guides/schema/click-to-edit). Examples for other supported frameworks are available at:
- [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router)
- [Remix](/docs/developer-guides/schema/click-to-edit-remix)
- [Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt)
- [Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js)
- [Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api)

<Alert theme="info">
If you are instrumenting a frontend you did not build from scratch, start with the `PreviewWrapper` component and a single simple field. Confirm the Edit button appears and the save refresh works before adding component attributes. Components require additional data from your GraphQL queries.
</Alert>

## Steps

1. [Install the Preview SDK](#install-the-preview-sdk).
2. [Create a PreviewWrapper component to enable the preview functionality](#create-the-previewwrapper-component).
3. [Set environment variables](#set-environment-variables).
4. [Add data attributes to your content elements](#add-data-attributes-to-content-elements).
5. [Set up the Preview widget in Studio](/docs/developer-guides/schema/click-to-edit#set-up-the-preview-widget-in-studio).
6. [Verify the setup](#verify-the-setup).

## Install the Preview SDK

To install the Preview SDK, run the following command:

```bash
npm install @hygraph/preview-sdk
```

## Create the PreviewWrapper component

The PreviewWrapper initializes the SDK and wraps your application content. The `HygraphPreview` component handles iframe and standalone mode detection automatically.

### Step 1: Create PreviewWrapper.tsx

Create `components/PreviewWrapper.tsx`:

```ts
// components/PreviewWrapper.tsx
'use client';

import { useRouter } from 'next/navigation';
import dynamic from 'next/dynamic';

const HygraphPreview = dynamic(
  () => import('@hygraph/preview-sdk/react').then(mod => ({ default: mod.HygraphPreview })),
  { ssr: false }
);

export function PreviewWrapper({ children }) {
  const router = useRouter();

  return (
    <HygraphPreview
      endpoint={process.env.NEXT_PUBLIC_HYGRAPH_ENDPOINT!}
      studioUrl={process.env.NEXT_PUBLIC_HYGRAPH_STUDIO_URL}
      debug={true}  // Optional: Enable console logging
      mode="iframe"  // Optional: 'iframe' | 'standalone' | 'auto'
      onSave={(entryId) => {  // Optional: Custom save handler
        console.log('Content saved:', entryId);
        router.refresh();
    }}
      overlay={{  // Optional: Customize overlay styling
      style: {
        borderColor: '#3b82f6',
        borderWidth: '2px',
        },
      button: {
        backgroundColor: '#3b82f6',
        color: 'white',
        },
    }}
      sync={{
        fieldFocus: true,  // Optional: Enable field focus sync from Studio
        fieldUpdate: false,  // Optional: Apply live field updates to Preview
    }}
    >
      {children}
    </HygraphPreview>
  );
}
```

### Step 2: Wrap children in layout.tsx

The `PreviewWrapper` must wrap `{children}` at the layout level. In Next.js App Router, `{children}` represents the rendered content of the active route. If the wrapper is absent, the SDK cannot register page content and Click to Edit will not work.

Import and apply the `PreviewWrapper` component in `app/layout.tsx`:

```ts
// app/layout.tsx
import { PreviewWrapper } from '@/components/PreviewWrapper';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <PreviewWrapper>{children}</PreviewWrapper>
      </body>
    </html>
  );
}
```

**Configuration properties**

| Property              | Required / Optional | Description |
|-----------------------|----------------------|-------------|
| `endpoint`            | **Required**         | Hygraph Content API endpoint. To learn how to retrieve the Content API endpoint, see [our docs](/docs/developer-guides/project/api-access#content-api). |
| `studioUrl`           | Optional (recommended) | Studio base URL. Defaults to `https://app.hygraph.com`. Set this if your Studio runs on a regional or custom domain. |
| `debug`               | Optional             | Enables verbose console logs to diagnose attribute issues. |
| `mode`                | Optional             | Forces a specific mode. Options: `'iframe'` \| `'standalone'` \| `'auto'`. Auto-detection works for most cases. |
| `onSave`              | Optional             | Runs after Hygraph reports a save and receives the entry ID for targeted revalidation. |
| `overlay`             | Optional             | Customize overlay border and button appearance. |
| `sync.fieldFocus`     | Optional             | Synchronizes field focus between Studio and the preview when an editor selects a field. |
| `sync.fieldUpdate`    | Optional             | Updates the preview immediately when field updates happen in Studio. Defaults to `false`. |
| `allowedOrigins`      | Optional             | Extends the list of domains that can host your preview iframe. Example: For shared preview environments (QA, staging), add the base URL here. |

## Set environment variables

Add the following to `.env.local` in your project's root directory. If you already have these from live preview setup, skip this step.

```bash
# .env.local
NEXT_PUBLIC_HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
NEXT_PUBLIC_HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token  # Optional: Required if your project uses authentication
```

**Content API endpoint**: Find this under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our documentation on the [Content API](/docs/developer-guides/project/api-access#content-api).

**Hygraph Studio base URL**: Copy from your browser's address bar in Studio. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.

**Permanent Auth Token**: Create under **Project Settings > Access > Permanent Auth Tokens**. Set the default content stage to **DRAFT**. Only required if your project enforces authentication on Content API requests. For more information, see our dedicated documentation on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).

## Add data attributes to content elements

Data attributes (`data-hygraph-*`) connect your rendered elements to specific Hygraph fields. The SDK reads these attributes and attaches Edit overlays automatically. The same attributes work for variants; no additional instrumentation is required. For the full attribute reference, see [Add data attributes to content elements](/docs/developer-guides/schema/click-to-edit#add-data-attributes-to-content-elements). 

The examples below use a recipe model. To bootstrap the same Hygraph project used here, follow the [project setup instructions](https://github.com/hygraph/preview-sdk/blob/main/examples/project-setup/README.md).

### Simple fields

Add `data-hygraph-entry-id` and `data-hygraph-field-api-id` to any element rendering a Hygraph field value.

```ts

// app/recipes/[id]/page.tsx

  return (
    <main>
      {/* Title */}
      <h1
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="title"
      >
        {recipe.title}
      </h1>

      {/* Description */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="description"
        data-hygraph-rich-text-format="html"
      >
        <div dangerouslySetInnerHTML={{ __html: recipe.description.html }} />
      </div>

      {/* Recipe Meta */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="prepTime"
      >
        {recipe.prepTime}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="cookTime"
      >
        {recipe.cookTime}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="servings"
      >
        {recipe.servings}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="difficulty"
      >
        {recipe.difficulty}
      </div>

      {/* Hero Image */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="heroImage"
      >
        {/* Example image rendering */}
        {recipe.heroImage?.url && (
          <img src={recipe.heroImage.url} alt={recipe.title} />
        )}
      </div>
    </main>
  );
```

### Component fields

Components require the `data-hygraph-component-chain` attribute so Studio can navigate to the correct nested field instance. Use the helper functions from `@hygraph/preview-sdk/core`:

```tsx
import {
  createComponentChainLink,
  createPreviewAttributes,
  withFieldPath,
} from '@hygraph/preview-sdk/core';
```

The `instanceId` in each chain link is the `id` field of the component instance returned in your GraphQL query. It is not the component type's API ID. Query for `id` on every component you want to instrument. See the GraphQL example in [Basic components](#basic-components) below.

#### Basic components

These are direct children of the Recipe model, and are not nested inside other components. Each one uses a single-link chain.

<Tabs>
  <TabsItem label="Ingredients">

```ts

// Type: Basic component
// Structure: `Recipe → ingredients[] → ingredient fields`
// Used for: `quantity`, `unit` fields
// Path depth: 1 level (Recipe → Ingredient)
// Chain link: 1

// app/recipes/[id]/page.tsx

{recipe.ingredients.map((ingredient, index) => {
  const chain = [createComponentChainLink('ingredients', ingredient.id)];
  const basePath = `ingredients.${index}`;
  const quantityAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'quantity',
      componentChain: chain,
    }),
    `${basePath}.quantity`
  );
  // ... used for quantity, unit fields
})}
```

  </TabsItem>
  <TabsItem label="Recipe steps">

```ts

// Type: Basic component
// Structure: `Recipe → recipeSteps[] → step fields`
// Used for: `stepNumber`, `title`, `instruction`, `estimatedTime`
// Path depth: 1 level (Recipe → Recipe Step)
// Chain link: 1

// app/recipes/[id]/page.tsx

{recipe.recipeSteps.map((step, index) => {
  const chain = [createComponentChainLink('recipeSteps', step.id)];
  const stepBasePath = `recipeSteps.${index}`;
  const stepNumberAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'stepNumber',
      componentChain: chain,
    }),
    `${stepBasePath}.stepNumber`
  );
  // ... used for stepNumber, title, instruction, estimatedTime
})}
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for basic components:

```graphql
query GetRecipe($id: ID!) {
  recipe(where: { id: $id }, stage: DRAFT) {
    id
    title
    ingredients {
      id        # instanceId for the ingredient component
      quantity
      unit
    }
    recipeSteps {
      id        # instanceId for the step component
      stepNumber
      instruction { html }
    }
  }
}
```

#### Nested components

Nested components require a multi-link chain, ordered from the outermost to the innermost component.

<Tabs>
  <TabsItem label="Equipment within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → equipment[] → equipment fields`
// Used for: `name`, `required`, `alternatives`, `notes` fields
// Path depth: 2 levels (Recipe → Recipe Step → Equipment)
// Chain links: 2

// app/recipes/[id]/page.tsx

{step.equipment.map((equip, equipIndex) => {
  const equipChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('equipment', equip.id)
  ];
  const equipBasePath = `${stepBasePath}.equipment.${equipIndex}`;
  // ... used for name, required, alternatives, notes fields
})}
```

  </TabsItem>
  <TabsItem label="Ingredients used within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → ingredientsUsed[] → ingredient fields`
// Used for: `ingredientName`, `preparation`, `timing`, `notes` fields
// Path depth: 2 levels (Recipe → Recipe Step → Ingredient Reference)
// Chain links: 2

// app/recipes/[id]/page.tsx

{step.ingredientsUsed.map((ingred, ingredIndex) => {
  const ingredChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('ingredientsUsed', ingred.id)
  ];
  const ingredBasePath = `${stepBasePath}.ingredientsUsed.${ingredIndex}`;
  // ... used for ingredientName, preparation, timing, notes fields
})}
```

  </TabsItem>
  <TabsItem label="Tips within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → tips[] → tip fields`
// Used for: `icon`, `title`, `content` fields
// Path depth: 2 levels (Recipe → Recipe Step → Tip)
// Chain links: 2

// app/recipes/[id]/page.tsx

{step.tips.map((tip, tipIndex) => {
  const tipChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('tips', tip.id)
  ];
  const tipBasePath = `${stepBasePath}.tips.${tipIndex}`;
  // ... used for icon, title, content fields
})}
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for nested components. Extend your basic component query:

```graphql
recipeSteps {
  id
  stepNumber
  instruction { html }
  equipment {
    id        # instanceId for nested equipment
    name
    required
  }
  tips {
    id        # instanceId for nested tips
    title
    content { html }
  }
}
```

#### Modular components

Modular components can be one of several types. Use `__typename` to branch and build the chain per type.

The examples below display aliased GraphQL fields such as `section.tipTitle` and `section.tipContent`. Those come from query aliases (`tipTitle: title`, `tipContent: content`). `fieldApiId` must still use the schema API IDs (`title`, `content`).

<Tabs>
  <TabsItem label="Featured Content">

```ts

// Type: Modular component
// Structure: `Recipe → featuredContent (ProTip | VideoEmbed | IngredientSpotlight)`
// Used for: Single featured content section
// Path depth: 1 level
// Chain link: 1

// app/recipes/[id]/page.tsx

// Chain creation
const section = recipe.featuredContent;
const chain = [createComponentChainLink('featuredContent', section.id)];
const basePath = 'featuredContent';

// Switch
switch (section.__typename) {
  case 'ProTip': {
    const proTipIconAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'icon',
        componentChain: chain,
      }),
      `${basePath}.icon`
    );
    const proTipTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'title',
        componentChain: chain,
      }),
      `${basePath}.title`
    );
    const proTipContentAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'content',
        componentChain: chain,
      }),
      `${basePath}.content`
    );

    return (
      <div>
        <div {...proTipIconAttributes}>
          {section.icon || '⭐'}
        </div>
        <h3 {...proTipTitleAttributes}>
          {section.tipTitle}
        </h3>
        <div
          dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
          {...proTipContentAttributes}
          data-hygraph-rich-text-format="html"
        />
      </div>
    );
  }

  case 'VideoEmbed': {
    const videoTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'title',
        componentChain: chain,
      }),
      `${basePath}.title`
    );
    const videoUrlAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'videoUrl',
        componentChain: chain,
      }),
      `${basePath}.videoUrl`
    );
    const videoDescriptionAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'description',
        componentChain: chain,
      }),
      `${basePath}.description`
    );

    return (
      <div>
        <h3 {...videoTitleAttributes}>
          {section.videoTitle}
        </h3>
        <div {...videoUrlAttributes}>
          {/* Video embed logic */}
        </div>
        {section.videoDescription && (
          <div
            dangerouslySetInnerHTML={{ __html: section.videoDescription.html }}
            {...videoDescriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
        )}
      </div>
    );
  }

  case 'IngredientSpotlight': {
    const spotlightImageAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'image',
        componentChain: chain,
      }),
      `${basePath}.image`
    );
    const spotlightTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'ingredient',
        componentChain: chain,
      }),
      `${basePath}.ingredient`
    );
    const spotlightDescriptionAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'description',
        componentChain: chain,
      }),
      `${basePath}.description`
    );
    const spotlightSubstitutesAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'substitutes',
        componentChain: chain,
      }),
      `${basePath}.substitutes`
    );

    return (
      <div>
        <div {...spotlightImageAttributes}>
          {section.ingredientImage ? (
            <img
              src={section.ingredientImage.url}
              alt={section.ingredient?.name || 'Ingredient'}
              width={120}
              height={120}
            />
          ) : (
            <div>🌿</div>
          )}
        </div>
        <h3 {...spotlightTitleAttributes}>
          Star Ingredient: <span>{section.ingredient?.name || 'Unknown'}</span>
        </h3>
        <div
          dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
          {...spotlightDescriptionAttributes}
          data-hygraph-rich-text-format="html"
        />
        {section.substitutes && (
          <span {...spotlightSubstitutesAttributes}>
            {section.substitutes}
          </span>
        )}
      </div>
    );
  }

  default:
    return null;
}
```

  </TabsItem>
  <TabsItem label="Additional Sections">

```ts

// Type: Modular component
// Structure: `Recipe → additionalSections[] (ProTip | VideoEmbed | IngredientSpotlight)[]`
// Used for: Multiple additional content sections
// Path depth: 1 level
// Chain link: 1

// app/recipes/[id]/page.tsx

{recipe.additionalSections.map((section, index) => {
  // Chain creation
  const chain = [createComponentChainLink('additionalSections', section.id)];
  const basePath = `additionalSections.${index}`;

  // Switch
  switch (section.__typename) {
    case 'ProTip': {
      const proTipListIconAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'icon',
          componentChain: chain,
        }),
        `${basePath}.icon`
      );
      const proTipListTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const proTipListContentAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'content',
          componentChain: chain,
        }),
        `${basePath}.content`
      );

      return (
        <div key={section.id}>
          <div {...proTipListIconAttributes}>
            {section.icon || '💡'}
          </div>
          <h3 {...proTipListTitleAttributes}>
            {section.tipTitle}
          </h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
            {...proTipListContentAttributes}
            data-hygraph-rich-text-format="html"
          />
        </div>
      );
    }

    case 'VideoEmbed': {
      const listVideoTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const listVideoUrlAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'videoUrl',
          componentChain: chain,
        }),
        `${basePath}.videoUrl`
      );
      const listVideoDescriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );

      return (
        <div key={section.id}>
          <h3 {...listVideoTitleAttributes}>
            {section.videoTitle}
          </h3>
          <div {...listVideoUrlAttributes}>
            {/* Video embed logic */}
          </div>
          {section.videoDescription && (
            <div
              dangerouslySetInnerHTML={{ __html: section.videoDescription.html }}
              {...listVideoDescriptionAttributes}
              data-hygraph-rich-text-format="html"
            />
          )}
        </div>
      );
    }

    case 'IngredientSpotlight': {
      const listSpotlightImageAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'image',
          componentChain: chain,
        }),
        `${basePath}.image`
      );
      const listSpotlightTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'ingredient',
          componentChain: chain,
        }),
        `${basePath}.ingredient`
      );
      const listSpotlightDescriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );
      const listSpotlightSubstitutesAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'substitutes',
          componentChain: chain,
        }),
        `${basePath}.substitutes`
      );

      return (
        <div key={section.id}>
          <div {...listSpotlightImageAttributes}>
            {section.ingredientImage ? (
              <img
                src={section.ingredientImage.url}
                alt={section.ingredient?.name || 'Ingredient'}
                width={80}
                height={80}
              />
            ) : (
              <div>🥬</div>
            )}
          </div>
          <h3 {...listSpotlightTitleAttributes}>
            Featured: <span>{section.ingredient?.name || 'Unknown'}</span>
          </h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
            {...listSpotlightDescriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
          {section.substitutes && (
            <span {...listSpotlightSubstitutesAttributes}>
              {section.substitutes}
            </span>
          )}
        </div>
      );
    }

    default:
      return null;
  }
})}
```

  </TabsItem>
</Tabs>

### Full example

```ts

// app/recipes/[id]/page.tsx

import { createComponentChainLink, createPreviewAttributes, withFieldPath } from '@hygraph/preview-sdk/core';

// Basic fields

<h1 data-hygraph-field-api-id="title" data-hygraph-entry-id={recipe.id}>
  {recipe.title}
</h1>

<div
  data-hygraph-field-api-id="description"
  data-hygraph-entry-id={recipe.id}
  data-hygraph-rich-text-format="html"
>
  <div dangerouslySetInnerHTML={{ __html: recipe.description.html }} />
</div>

<div data-hygraph-field-api-id="prepTime" data-hygraph-entry-id={recipe.id}>
  {recipe.prepTime}min
</div>

<div data-hygraph-entry-id={recipe.id} data-hygraph-field-api-id="categories">
  {recipe.categories.map((category) => (
    <span key={category.id}>{category.name}</span>
  ))}
</div>

// Basic components

// Ingredients
{recipe.ingredients.map((ingredient, index) => {
  const chain = [createComponentChainLink('ingredients', ingredient.id)];
  const basePath = `ingredients.${index}`;

  const quantityAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'quantity',
      componentChain: chain,
    }),
    `${basePath}.quantity`
  );

  const unitAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'unit',
      componentChain: chain,
    }),
    `${basePath}.unit`
  );

  return (
    <div key={ingredient.id}>
      <span>{ingredient.ingredient?.name}</span>
      <span {...quantityAttributes}>{ingredient.quantity}</span>
      <span {...unitAttributes}>{ingredient.unit}</span>
    </div>
  );
})}

// Recipe Steps (with nested components)
{recipe.recipeSteps.map((step, index) => {
  const chain = [createComponentChainLink('recipeSteps', step.id)];
  const stepBasePath = `recipeSteps.${index}`;

  const stepNumberAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'stepNumber',
      componentChain: chain,
    }),
    `${stepBasePath}.stepNumber`
  );

  const stepTitleAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'title',
      componentChain: chain,
    }),
    `${stepBasePath}.title`
  );

  const instructionAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'instruction',
      componentChain: chain,
    }),
    `${stepBasePath}.instruction`
  );

  return (
    <div key={step.id}>
      <span {...stepNumberAttributes}>{step.stepNumber}</span>
      {step.title && <h3 {...stepTitleAttributes}>{step.title}</h3>}
      <div
        dangerouslySetInnerHTML={{ __html: step.instruction.html }}
        {...instructionAttributes}
        data-hygraph-rich-text-format="html"
      />

      {/* Nested: Equipment within Recipe Steps */}
      {step.equipment?.map((equip, equipIndex) => {
        const equipChain = [
          createComponentChainLink('recipeSteps', step.id),
          createComponentChainLink('equipment', equip.id),
        ];
        const equipBasePath = `${stepBasePath}.equipment.${equipIndex}`;

        const nameAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'name',
            componentChain: equipChain,
          }),
          `${equipBasePath}.name`
        );

        const requiredAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'required',
            componentChain: equipChain,
          }),
          `${equipBasePath}.required`
        );

        return (
          <div key={equip.id}>
            <span {...nameAttributes}>{equip.name}</span>
            {equip.required && <span {...requiredAttributes}>Required</span>}
          </div>
        );
      })}

      {/* Nested: Ingredients Used within Recipe Steps */}
      {step.ingredientsUsed?.map((ingred, ingredIndex) => {
        const ingredChain = [
          createComponentChainLink('recipeSteps', step.id),
          createComponentChainLink('ingredientsUsed', ingred.id),
        ];
        const ingredBasePath = `${stepBasePath}.ingredientsUsed.${ingredIndex}`;

        const ingredientNameAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'ingredientName',
            componentChain: ingredChain,
          }),
          `${ingredBasePath}.ingredientName`
        );

        return (
          <div key={ingred.id}>
            <span {...ingredientNameAttributes}>{ingred.ingredientName}</span>
          </div>
        );
      })}

      {/* Nested: Tips within Recipe Steps */}
      {step.tips?.map((tip, tipIndex) => {
        const tipChain = [
          createComponentChainLink('recipeSteps', step.id),
          createComponentChainLink('tips', tip.id),
        ];
        const tipBasePath = `${stepBasePath}.tips.${tipIndex}`;

        const titleAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: tipChain,
          }),
          `${tipBasePath}.title`
        );

        const contentAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'content',
            componentChain: tipChain,
          }),
          `${tipBasePath}.content`
        );

        return (
          <div key={tip.id}>
            <h5 {...titleAttributes}>{tip.title}</h5>
            <div
              dangerouslySetInnerHTML={{ __html: tip.content.html }}
              {...contentAttributes}
              data-hygraph-rich-text-format="html"
            />
          </div>
        );
      })}
    </div>
  );
})}


// Modular components

// Featured Content (Single)
{recipe.featuredContent && (() => {
  const section = recipe.featuredContent;
  const chain = [createComponentChainLink('featuredContent', section.id)];
  const basePath = 'featuredContent';

  switch (section.__typename) {
    case 'ProTip': {
      const iconAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'icon',
          componentChain: chain,
        }),
        `${basePath}.icon`
      );
      const titleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const contentAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'content',
          componentChain: chain,
        }),
        `${basePath}.content`
      );

      return (
        <div>
          <div {...iconAttributes}>{section.icon}</div>
          <h3 {...titleAttributes}>{section.tipTitle}</h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
            {...contentAttributes}
            data-hygraph-rich-text-format="html"
          />
        </div>
      );
    }

    case 'VideoEmbed': {
      const titleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const videoUrlAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'videoUrl',
          componentChain: chain,
        }),
        `${basePath}.videoUrl`
      );

      return (
        <div>
          <h3 {...titleAttributes}>{section.videoTitle}</h3>
          <div {...videoUrlAttributes}>Video</div>
        </div>
      );
    }

    case 'IngredientSpotlight': {
      const imageAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'image',
          componentChain: chain,
        }),
        `${basePath}.image`
      );
      const ingredientAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'ingredient',
          componentChain: chain,
        }),
        `${basePath}.ingredient`
      );
      const descriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );

      return (
        <div>
          <div {...imageAttributes}>Image</div>
          <h3 {...ingredientAttributes}>{section.ingredient?.name}</h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
            {...descriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
        </div>
      );
    }

    default:
      return null;
  }
})()}

// Additional Sections (Array)
{recipe.additionalSections.map((section, index) => {
  const chain = [createComponentChainLink('additionalSections', section.id)];
  const basePath = `additionalSections.${index}`;

  switch (section.__typename) {
    case 'ProTip': {
      const iconAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'icon',
          componentChain: chain,
        }),
        `${basePath}.icon`
      );
      const titleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const contentAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'content',
          componentChain: chain,
        }),
        `${basePath}.content`
      );

      return (
        <div key={section.id}>
          <div {...iconAttributes}>{section.icon}</div>
          <h3 {...titleAttributes}>{section.tipTitle}</h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
            {...contentAttributes}
            data-hygraph-rich-text-format="html"
          />
        </div>
      );
    }

    case 'VideoEmbed': {
      const titleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );

      return (
        <div key={section.id}>
          <h3 {...titleAttributes}>{section.videoTitle}</h3>
        </div>
      );
    }

    case 'IngredientSpotlight': {
      const imageAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'image',
          componentChain: chain,
        }),
        `${basePath}.image`
      );
      const ingredientAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'ingredient',
          componentChain: chain,
        }),
        `${basePath}.ingredient`
      );

      return (
        <div key={section.id}>
          <div {...imageAttributes}>Image</div>
          <h3 {...ingredientAttributes}>{section.ingredient?.name}</h3>
        </div>
      );
    }

    default:
      return null;
  }
})}
```

## Verify the setup

1. Open an entry in Studio for the model you configured.
2. In the right sidebar, click **Open live preview**. The preview should load alongside the entry form.
3. Hover over an element you tagged with `data-hygraph-*` attributes. An **Edit** button should appear.
4. Click **Edit**. Studio should scroll to and focus the corresponding field in the entry form.
5. Edit the field value and click **Save & Preview**. The preview should refresh and show the updated content.

If you are working with variants, no additional setup is required. Clicking a tagged element while a variant is open focuses the field directly in the variant overlay.

If the **Edit** button does not appear at step 3, add `debug={true}` to your `HygraphPreview` component and check the browser console for missing attribute warnings. For component fields, confirm your GraphQL query includes the `id` field on each component and that the `instanceId` values in your chain match what the query returns. For more information, see [Troubleshooting](/docs/developer-guides/schema/click-to-edit#troubleshooting).

## Related docs

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): General setup steps, attribute reference, Studio widget configuration, and troubleshooting.
- [Click to Edit - Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api): React hooks, Preview methods, DOM events, and helpers for dynamic content.
- [Live preview setup](/docs/developer-guides/schema/live-preview): Configure the Studio preview iframe before deploying Click to Edit to editors.

---
# Click to Edit - Next.js Pages Router

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit-next-js-pages-router

This page walks through implementing Click to Edit in a Next.js Pages Router project using the <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Hygraph Preview SDK</Link>. By the end, editors can click any instrumented element in the preview to jump directly to that field in Studio.

For the general setup overview and configuration reference, see [Click to Edit setup](/docs/developer-guides/schema/click-to-edit). Examples for other supported frameworks are available at:
- [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router)
- [Remix](/docs/developer-guides/schema/click-to-edit-remix)
- [Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt)
- [Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js)
- [Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api)

<Alert theme="info">
If you are instrumenting a frontend you did not build from scratch, start with the `PreviewWrapper` component and a single simple field. Confirm the Edit button appears and the save refresh works before adding component attributes. Components require additional data from your GraphQL queries.
</Alert>

## Steps

1. [Install the Preview SDK](#install-the-preview-sdk).
2. [Create a PreviewWrapper component to enable the preview functionality](#create-the-previewwrapper-component).
3. [Set environment variables](#set-environment-variables).
4. [Add data attributes to your content elements](#add-data-attributes-to-content-elements).
5. [Set up the Preview widget in Studio](/docs/developer-guides/schema/click-to-edit#set-up-the-preview-widget-in-studio).
6. [Verify the setup](#verify-the-setup).

## Install the Preview SDK

To install the Preview SDK, run the following command:

```bash
npm install @hygraph/preview-sdk
```

## Create the PreviewWrapper component

The PreviewWrapper initializes the SDK and wraps your application content. Pages Router has no server components, so the SDK's React module loads client-side through a manual dynamic `import()` once the component has mounted, rather than through the single `next/dynamic` call used in App Router.

### Step 1: Create PreviewWrapper.tsx

Create `components/PreviewWrapper.tsx`:

```ts
// components/PreviewWrapper.tsx
import { useRouter } from 'next/router';
import { useEffect, useState, useMemo, useLayoutEffect } from 'react';
import type { ComponentType, ReactNode } from 'react';

interface PreviewWrapperProps {
  children: ReactNode;
}

export function PreviewWrapper({ children }: PreviewWrapperProps) {
  const router = useRouter();
  const [PreviewComponent, setPreviewComponent] = useState<ComponentType<any> | null>(null);
  const [isMounted, setIsMounted] = useState(false);

  // useLayoutEffect ensures React is fully initialized before loading the SDK
  useLayoutEffect(() => {
    setIsMounted(true);
  }, []);

  useEffect(() => {
    if (!isMounted) return;

    import('@hygraph/preview-sdk/react')
      .then((mod) => {
        setPreviewComponent(() => mod.HygraphPreview);
      })
      .catch((error) => {
        console.error('Failed to load Hygraph Preview SDK:', error);
      });
  }, [isMounted]);

  const handleSave = useMemo(() => {
    return (entryId: string) => {  // Optional: Custom save handler
      console.log('Content saved:', entryId);
      router.replace(router.asPath);
    };
  }, [router]);

  // Don't render the preview until mounted and the SDK component is loaded
  if (!isMounted || !PreviewComponent) {
    return <>{children}</>;
  }

  return (
    <PreviewComponent
      endpoint={process.env.NEXT_PUBLIC_HYGRAPH_ENDPOINT!}
      studioUrl={process.env.NEXT_PUBLIC_HYGRAPH_STUDIO_URL}
      debug={true}  // Optional: Enable console logging
      mode="iframe"  // Optional: 'iframe' | 'standalone' | 'auto'
      onSave={handleSave}
      overlay={{  // Optional: Customize overlay styling
        style: {
          borderColor: '#3b82f6',
          borderWidth: '2px',
        },
        button: {
          backgroundColor: '#3b82f6',
          color: 'white',
        },
      }}
      sync={{
        fieldFocus: true,  // Optional: Enable field focus sync from Studio
        fieldUpdate: false,  // Optional: Apply live field updates to Preview
      }}
    >
      {children}
    </PreviewComponent>
  );
}
```

### Step 2: Register PreviewWrapper in _app.tsx

Pages Router has no root layout file. Register `PreviewWrapper` in `pages/_app.tsx` instead, and load it with `next/dynamic` and `ssr: false`. If the wrapper is absent, the SDK cannot register page content and Click to Edit will not work.

```tsx
// pages/_app.tsx
import type { AppProps } from 'next/app';
import dynamic from 'next/dynamic';

const PreviewWrapper = dynamic(
  () => import('@/components/PreviewWrapper').then(mod => ({ default: mod.PreviewWrapper })),
  { ssr: false }
);

export default function App({ Component, pageProps }: AppProps) {
  return (
    <PreviewWrapper>
      <Component {...pageProps} />
    </PreviewWrapper>
  );
}
```

**Configuration properties**

| Property              | Required / Optional | Description |
|-----------------------|----------------------|-------------|
| `endpoint`            | **Required**         | Hygraph Content API endpoint. To learn how to retrieve the Content API endpoint, see [our docs](/docs/developer-guides/project/api-access#content-api). |
| `studioUrl`           | Optional (recommended) | Studio base URL. Defaults to `https://app.hygraph.com`. Set this if your Studio runs on a regional or custom domain. |
| `debug`               | Optional             | Enables verbose console logs to diagnose attribute issues. |
| `mode`                | Optional             | Forces a specific mode. Options: `'iframe'` \| `'standalone'` \| `'auto'`. Auto-detection works for most cases. |
| `onSave`              | Optional             | Runs after Hygraph reports a save and receives the entry ID for targeted revalidation. |
| `overlay`             | Optional             | Customize overlay border and button appearance. |
| `sync.fieldFocus`     | Optional             | Synchronizes field focus between Studio and the preview when an editor selects a field. |
| `sync.fieldUpdate`    | Optional             | Updates the preview immediately when field updates happen in Studio. Defaults to `false`. |
| `allowedOrigins`      | Optional             | Extends the list of domains that can host your preview iframe. Example: For shared preview environments (QA, staging), add the base URL here. |

## Set environment variables

Add the following to `.env.local` in your project's root directory. If you already have these from live preview setup, skip this step.

```bash
# .env.local
NEXT_PUBLIC_HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
NEXT_PUBLIC_HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token  # Optional: Required if your project uses authentication
```

**Content API endpoint**: Find this under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our documentation on the [Content API](/docs/developer-guides/project/api-access#content-api).

**Hygraph Studio base URL**: Copy from your browser's address bar in Studio. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.

**Permanent Auth Token**: Create under **Project Settings > Access > Permanent Auth Tokens**. Set the default content stage to **DRAFT**. Only required if your project enforces authentication on Content API requests. For more information, see our dedicated documentation on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).

## Add data attributes to content elements

Data attributes (`data-hygraph-*`) connect your rendered elements to specific Hygraph fields. The SDK reads these attributes and attaches Edit overlays automatically. The same attributes work for variants; no additional instrumentation is required. For the full attribute reference, see [Add data attributes to content elements](/docs/developer-guides/schema/click-to-edit#add-data-attributes-to-content-elements).

The examples below use a recipe model. To bootstrap the same Hygraph project used here, follow the <Link href="https://github.com/hygraph/preview-sdk/blob/main/examples/project-setup/README.md" target="_blank">project setup instructions</Link>.

Pages Router fetches the entry with `getServerSideProps` (or `getStaticProps`) and passes it to the page component as a prop. The route `id` comes from `context.params`, not `useParams()`.

```ts
// pages/recipes/[id].tsx
import { GetServerSideProps } from 'next';

export const getServerSideProps: GetServerSideProps = async (context) => {
  const { id } = context.params!;
  const recipe = await getRecipe(id as string);

  if (!recipe) {
    return { notFound: true };
  }

  return { props: { recipe } };
};

export default function RecipePage({ recipe }) {
  // ... rendered below
}
```

### Simple fields

Add `data-hygraph-entry-id` and `data-hygraph-field-api-id` to any element rendering a Hygraph field value.

```tsx

// pages/recipes/[id].tsx

  return (
    <main>
      {/* Title */}
      <h1
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="title"
      >
        {recipe.title}
      </h1>

      {/* Description */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="description"
        data-hygraph-rich-text-format="html"
      >
        <div dangerouslySetInnerHTML={{ __html: recipe.description.html }} />
      </div>

      {/* Recipe Meta */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="prepTime"
      >
        {recipe.prepTime}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="cookTime"
      >
        {recipe.cookTime}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="servings"
      >
        {recipe.servings}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="difficulty"
      >
        {recipe.difficulty}
      </div>

      {/* Hero Image */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="heroImage"
      >
        {/* Example image rendering */}
        {recipe.heroImage?.url && (
          <img src={recipe.heroImage.url} alt={recipe.title} />
        )}
      </div>
    </main>
  );
```

### Component fields

Components require the `data-hygraph-component-chain` attribute so Studio can navigate to the correct nested field instance. Use the helper functions from `@hygraph/preview-sdk/core`:

```tsx
import {
  createComponentChainLink,
  createPreviewAttributes,
  withFieldPath,
} from '@hygraph/preview-sdk/core';
```

The `instanceId` in each chain link is the `id` field of the component instance returned in your GraphQL query. It is not the component type's API ID. Query for `id` on every component you want to instrument. See the GraphQL example in [Basic components](#basic-components) below.

#### Basic components

These are direct children of the Recipe model, and are not nested inside other components. Each one uses a single-link chain.

<Tabs>
  <TabsItem label="Ingredients">

```ts

// Type: Basic component
// Structure: `Recipe → ingredients[] → ingredient fields`
// Used for: `quantity`, `unit` fields
// Path depth: 1 level (Recipe → Ingredient)
// Chain link: 1

// pages/recipes/[id].tsx

{recipe.ingredients.map((ingredient, index) => {
  const chain = [createComponentChainLink('ingredients', ingredient.id)];
  const basePath = `ingredients.${index}`;
  const quantityAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'quantity',
      componentChain: chain,
    }),
    `${basePath}.quantity`
  );
  // ... used for quantity, unit fields
})}
```

  </TabsItem>
  <TabsItem label="Recipe steps">

```ts

// Type: Basic component
// Structure: `Recipe → recipeSteps[] → step fields`
// Used for: `stepNumber`, `title`, `instruction`, `estimatedTime`
// Path depth: 1 level (Recipe → Recipe Step)
// Chain link: 1

// pages/recipes/[id].tsx

{recipe.recipeSteps.map((step, index) => {
  const chain = [createComponentChainLink('recipeSteps', step.id)];
  const stepBasePath = `recipeSteps.${index}`;
  const stepNumberAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'stepNumber',
      componentChain: chain,
    }),
    `${stepBasePath}.stepNumber`
  );
  // ... used for stepNumber, title, instruction, estimatedTime
})}
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for basic components:

```graphql
query GetRecipe($id: ID!) {
  recipe(where: { id: $id }, stage: DRAFT) {
    id
    title
    ingredients {
      id        # instanceId for the ingredient component
      quantity
      unit
    }
    recipeSteps {
      id        # instanceId for the step component
      stepNumber
      instruction { html }
    }
  }
}
```

#### Nested components

Nested components require a multi-link chain, ordered from the outermost to the innermost component.

<Tabs>
  <TabsItem label="Equipment within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → equipment[] → equipment fields`
// Used for: `name`, `required`, `alternatives`, `notes` fields
// Path depth: 2 levels (Recipe → Recipe Step → Equipment)
// Chain links: 2

// pages/recipes/[id].tsx

{step.equipment.map((equip, equipIndex) => {
  const equipChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('equipment', equip.id)
  ];
  const equipBasePath = `${stepBasePath}.equipment.${equipIndex}`;
  // ... used for name, required, alternatives, notes fields
})}
```

  </TabsItem>
  <TabsItem label="Ingredients used within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → ingredientsUsed[] → ingredient fields`
// Used for: `ingredientName`, `preparation`, `timing`, `notes` fields
// Path depth: 2 levels (Recipe → Recipe Step → Ingredient Reference)
// Chain links: 2

// pages/recipes/[id].tsx

{step.ingredientsUsed.map((ingred, ingredIndex) => {
  const ingredChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('ingredientsUsed', ingred.id)
  ];
  const ingredBasePath = `${stepBasePath}.ingredientsUsed.${ingredIndex}`;
  // ... used for ingredientName, preparation, timing, notes fields
})}
```

  </TabsItem>
  <TabsItem label="Tips within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → tips[] → tip fields`
// Used for: `icon`, `title`, `content` fields
// Path depth: 2 levels (Recipe → Recipe Step → Tip)
// Chain links: 2

// pages/recipes/[id].tsx

{step.tips.map((tip, tipIndex) => {
  const tipChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('tips', tip.id)
  ];
  const tipBasePath = `${stepBasePath}.tips.${tipIndex}`;
  // ... used for icon, title, content fields
})}
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for nested components. Extend your basic component query:

```graphql
recipeSteps {
  id
  stepNumber
  instruction { html }
  equipment {
    id        # instanceId for nested equipment
    name
    required
  }
  tips {
    id        # instanceId for nested tips
    title
    content { html }
  }
}
```

#### Modular components

Modular components can be one of several types. Use `__typename` to branch and build the chain per type.

The examples below display aliased GraphQL fields such as `section.tipTitle` and `section.tipContent`. Those come from query aliases (`tipTitle: title`, `tipContent: content`). `fieldApiId` must still use the schema API IDs (`title`, `content`).

<Tabs>
  <TabsItem label="Featured Content">

```ts

// Type: Modular component
// Structure: `Recipe → featuredContent (ProTip | VideoEmbed | IngredientSpotlight)`
// Used for: Single featured content section
// Path depth: 1 level
// Chain link: 1

// pages/recipes/[id].tsx

// Chain creation
const section = recipe.featuredContent;
const chain = [createComponentChainLink('featuredContent', section.id)];
const basePath = 'featuredContent';

// Switch
switch (section.__typename) {
  case 'ProTip': {
    const proTipIconAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'icon',
        componentChain: chain,
      }),
      `${basePath}.icon`
    );
    const proTipTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'title',
        componentChain: chain,
      }),
      `${basePath}.title`
    );
    const proTipContentAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'content',
        componentChain: chain,
      }),
      `${basePath}.content`
    );

    return (
      <div>
        <div {...proTipIconAttributes}>
          {section.icon || '⭐'}
        </div>
        <h3 {...proTipTitleAttributes}>
          {section.tipTitle}
        </h3>
        <div
          dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
          {...proTipContentAttributes}
          data-hygraph-rich-text-format="html"
        />
      </div>
    );
  }

  case 'VideoEmbed': {
    const videoTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'title',
        componentChain: chain,
      }),
      `${basePath}.title`
    );
    const videoUrlAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'videoUrl',
        componentChain: chain,
      }),
      `${basePath}.videoUrl`
    );
    const videoDescriptionAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'description',
        componentChain: chain,
      }),
      `${basePath}.description`
    );

    return (
      <div>
        <h3 {...videoTitleAttributes}>
          {section.videoTitle}
        </h3>
        <div {...videoUrlAttributes}>
          {/* Video embed logic */}
        </div>
        {section.videoDescription && (
          <div
            dangerouslySetInnerHTML={{ __html: section.videoDescription.html }}
            {...videoDescriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
        )}
      </div>
    );
  }

  case 'IngredientSpotlight': {
    const spotlightImageAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'image',
        componentChain: chain,
      }),
      `${basePath}.image`
    );
    const spotlightTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'ingredient',
        componentChain: chain,
      }),
      `${basePath}.ingredient`
    );
    const spotlightDescriptionAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'description',
        componentChain: chain,
      }),
      `${basePath}.description`
    );
    const spotlightSubstitutesAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'substitutes',
        componentChain: chain,
      }),
      `${basePath}.substitutes`
    );

    return (
      <div>
        <div {...spotlightImageAttributes}>
          {section.ingredientImage ? (
            <img
              src={section.ingredientImage.url}
              alt={section.ingredient?.name || 'Ingredient'}
              width={120}
              height={120}
            />
          ) : (
            <div>🌿</div>
          )}
        </div>
        <h3 {...spotlightTitleAttributes}>
          Star Ingredient: <span>{section.ingredient?.name || 'Unknown'}</span>
        </h3>
        <div
          dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
          {...spotlightDescriptionAttributes}
          data-hygraph-rich-text-format="html"
        />
        {section.substitutes && (
          <span {...spotlightSubstitutesAttributes}>
            {section.substitutes}
          </span>
        )}
      </div>
    );
  }

  default:
    return null;
}
```

  </TabsItem>
  <TabsItem label="Additional Sections">

```ts

// Type: Modular component
// Structure: `Recipe → additionalSections[] (ProTip | VideoEmbed | IngredientSpotlight)[]`
// Used for: Multiple additional content sections
// Path depth: 1 level
// Chain link: 1

// pages/recipes/[id].tsx

{recipe.additionalSections.map((section, index) => {
  // Chain creation
  const chain = [createComponentChainLink('additionalSections', section.id)];
  const basePath = `additionalSections.${index}`;

  // Switch
  switch (section.__typename) {
    case 'ProTip': {
      const proTipListIconAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'icon',
          componentChain: chain,
        }),
        `${basePath}.icon`
      );
      const proTipListTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const proTipListContentAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'content',
          componentChain: chain,
        }),
        `${basePath}.content`
      );

      return (
        <div key={section.id}>
          <div {...proTipListIconAttributes}>
            {section.icon || '💡'}
          </div>
          <h3 {...proTipListTitleAttributes}>
            {section.tipTitle}
          </h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
            {...proTipListContentAttributes}
            data-hygraph-rich-text-format="html"
          />
        </div>
      );
    }

    case 'VideoEmbed': {
      const listVideoTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const listVideoUrlAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'videoUrl',
          componentChain: chain,
        }),
        `${basePath}.videoUrl`
      );
      const listVideoDescriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );

      return (
        <div key={section.id}>
          <h3 {...listVideoTitleAttributes}>
            {section.videoTitle}
          </h3>
          <div {...listVideoUrlAttributes}>
            {/* Video embed logic */}
          </div>
          {section.videoDescription && (
            <div
              dangerouslySetInnerHTML={{ __html: section.videoDescription.html }}
              {...listVideoDescriptionAttributes}
              data-hygraph-rich-text-format="html"
            />
          )}
        </div>
      );
    }

    case 'IngredientSpotlight': {
      const listSpotlightImageAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'image',
          componentChain: chain,
        }),
        `${basePath}.image`
      );
      const listSpotlightTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'ingredient',
          componentChain: chain,
        }),
        `${basePath}.ingredient`
      );
      const listSpotlightDescriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );
      const listSpotlightSubstitutesAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'substitutes',
          componentChain: chain,
        }),
        `${basePath}.substitutes`
      );

      return (
        <div key={section.id}>
          <div {...listSpotlightImageAttributes}>
            {section.ingredientImage ? (
              <img
                src={section.ingredientImage.url}
                alt={section.ingredient?.name || 'Ingredient'}
                width={80}
                height={80}
              />
            ) : (
              <div>🥬</div>
            )}
          </div>
          <h3 {...listSpotlightTitleAttributes}>
            Featured: <span>{section.ingredient?.name || 'Unknown'}</span>
          </h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
            {...listSpotlightDescriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
          {section.substitutes && (
            <span {...listSpotlightSubstitutesAttributes}>
              {section.substitutes}
            </span>
          )}
        </div>
      );
    }

    default:
      return null;
  }
})}
```

  </TabsItem>
</Tabs>

### Full example

```ts

// pages/recipes/[id].tsx

import { GetServerSideProps } from 'next';
import { createComponentChainLink, createPreviewAttributes, withFieldPath } from '@hygraph/preview-sdk/core';

export const getServerSideProps: GetServerSideProps = async (context) => {
  const { id } = context.params!;
  const recipe = await getRecipe(id as string);

  if (!recipe) {
    return { notFound: true };
  }

  return { props: { recipe } };
};

export default function RecipePage({ recipe }) {
  return (
    <main>
      {/* Basic fields */}

      <h1 data-hygraph-field-api-id="title" data-hygraph-entry-id={recipe.id}>
        {recipe.title}
      </h1>

      <div
        data-hygraph-field-api-id="description"
        data-hygraph-entry-id={recipe.id}
        data-hygraph-rich-text-format="html"
      >
        <div dangerouslySetInnerHTML={{ __html: recipe.description.html }} />
      </div>

      <div data-hygraph-field-api-id="prepTime" data-hygraph-entry-id={recipe.id}>
        {recipe.prepTime}min
      </div>

      <div data-hygraph-entry-id={recipe.id} data-hygraph-field-api-id="categories">
        {recipe.categories.map((category) => (
          <span key={category.id}>{category.name}</span>
        ))}
      </div>

      {/* Basic components */}

      {/* Ingredients */}
      {recipe.ingredients.map((ingredient, index) => {
        const chain = [createComponentChainLink('ingredients', ingredient.id)];
        const basePath = `ingredients.${index}`;

        const quantityAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'quantity',
            componentChain: chain,
          }),
          `${basePath}.quantity`
        );

        const unitAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'unit',
            componentChain: chain,
          }),
          `${basePath}.unit`
        );

        return (
          <div key={ingredient.id}>
            <span>{ingredient.ingredient?.name}</span>
            <span {...quantityAttributes}>{ingredient.quantity}</span>
            <span {...unitAttributes}>{ingredient.unit}</span>
          </div>
        );
      })}

      {/* Recipe Steps (with nested equipment) */}
      {recipe.recipeSteps.map((step, index) => {
        const chain = [createComponentChainLink('recipeSteps', step.id)];
        const stepBasePath = `recipeSteps.${index}`;

        const stepNumberAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'stepNumber',
            componentChain: chain,
          }),
          `${stepBasePath}.stepNumber`
        );

        const stepTitleAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: chain,
          }),
          `${stepBasePath}.title`
        );

        const instructionAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'instruction',
            componentChain: chain,
          }),
          `${stepBasePath}.instruction`
        );

        return (
          <div key={step.id}>
            <span {...stepNumberAttributes}>{step.stepNumber}</span>
            {step.title && <h3 {...stepTitleAttributes}>{step.title}</h3>}
            <div
              dangerouslySetInnerHTML={{ __html: step.instruction.html }}
              {...instructionAttributes}
              data-hygraph-rich-text-format="html"
            />

            {/* Nested: Equipment within Recipe Steps */}
            {step.equipment?.map((equip, equipIndex) => {
              const equipChain = [
                createComponentChainLink('recipeSteps', step.id),
                createComponentChainLink('equipment', equip.id),
              ];
              const equipBasePath = `${stepBasePath}.equipment.${equipIndex}`;

              const nameAttributes = withFieldPath(
                createPreviewAttributes({
                  entryId: recipe.id,
                  fieldApiId: 'name',
                  componentChain: equipChain,
                }),
                `${equipBasePath}.name`
              );

              const requiredAttributes = withFieldPath(
                createPreviewAttributes({
                  entryId: recipe.id,
                  fieldApiId: 'required',
                  componentChain: equipChain,
                }),
                `${equipBasePath}.required`
              );

              return (
                <div key={equip.id}>
                  <span {...nameAttributes}>{equip.name}</span>
                  {equip.required && <span {...requiredAttributes}>Required</span>}
                </div>
              );
            })}
          </div>
        );
      })}

      {/* Modular components */}

      {/* Featured Content (Single) */}
      {recipe.featuredContent && (() => {
        const section = recipe.featuredContent;
        const chain = [createComponentChainLink('featuredContent', section.id)];
        const basePath = 'featuredContent';

        switch (section.__typename) {
          case 'ProTip': {
            const iconAttributes = withFieldPath(
              createPreviewAttributes({
                entryId: recipe.id,
                fieldApiId: 'icon',
                componentChain: chain,
              }),
              `${basePath}.icon`
            );
            const titleAttributes = withFieldPath(
              createPreviewAttributes({
                entryId: recipe.id,
                fieldApiId: 'title',
                componentChain: chain,
              }),
              `${basePath}.title`
            );
            const contentAttributes = withFieldPath(
              createPreviewAttributes({
                entryId: recipe.id,
                fieldApiId: 'content',
                componentChain: chain,
              }),
              `${basePath}.content`
            );

            return (
              <div>
                <div {...iconAttributes}>{section.icon}</div>
                <h3 {...titleAttributes}>{section.tipTitle}</h3>
                <div
                  dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
                  {...contentAttributes}
                  data-hygraph-rich-text-format="html"
                />
              </div>
            );
          }

          default:
            return null;
        }
      })()}
    </main>
  );
}
```

## Verify the setup

1. Open an entry in Studio for the model you configured.
2. In the right sidebar, click **Open live preview**. The preview should load alongside the entry form.
3. Hover over an element you tagged with `data-hygraph-*` attributes. An **Edit** button should appear.
4. Click **Edit**. Studio should scroll to and focus the corresponding field in the entry form.
5. Edit the field value and click **Save & Preview**. The preview should refresh and show the updated content.

If you are working with variants, no additional setup is required. Clicking a tagged element while a variant is open focuses the field directly in the variant overlay.

If the **Edit** button does not appear at step 3, add `debug={true}` to your `PreviewComponent` and check the browser console for missing attribute warnings. For component fields, confirm your GraphQL query includes the `id` field on each component and that the `instanceId` values in your chain match what the query returns. For more information, see [Troubleshooting](/docs/developer-guides/schema/click-to-edit#troubleshooting).

## Related docs

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): General setup steps, attribute reference, Studio widget configuration, and troubleshooting.
- [Click to Edit - Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api): React hooks, Preview methods, DOM events, and helpers for dynamic content.
- [Live preview setup](/docs/developer-guides/schema/live-preview): Configure the Studio preview iframe before deploying Click to Edit to editors.


---
# Click to Edit - Remix

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit-remix

This page walks through implementing Click to Edit in a Remix project using the <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Hygraph Preview SDK</Link>. By the end, editors can click any instrumented element in the preview to jump directly to that field in Studio.

For the general setup overview and configuration reference, see [Click to Edit setup](/docs/developer-guides/schema/click-to-edit). Examples for other supported frameworks are available at:
- [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router)
- [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router)
- [Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt)
- [Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js)
- [Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api)

<Alert theme="info">
If you are instrumenting a frontend you did not build from scratch, start with the `PreviewWrapper` component and a single simple field. Confirm the Edit button appears and the save refresh works before adding component attributes. Components require additional data from your GraphQL queries.
</Alert>

## Steps

1. [Install the Preview SDK](#install-the-preview-sdk).
2. [Create a PreviewWrapper component to enable the preview functionality](#create-the-previewwrapper-component).
3. [Set environment variables](#set-environment-variables).
4. [Add data attributes to your content elements](#add-data-attributes-to-content-elements).
5. [Set up the Preview widget in Studio](/docs/developer-guides/schema/click-to-edit#set-up-the-preview-widget-in-studio).
6. [Verify the setup](#verify-the-setup).

## Install the Preview SDK

To install the Preview SDK, run the following command:

```bash
npm install @hygraph/preview-sdk
```

## Create the PreviewWrapper component

The PreviewWrapper initializes the SDK and wraps your application content. Remix does not expose server environment variables to the client automatically, so `endpoint` and `studioUrl` are read from a `window.ENV` object populated by the root route's loader, rather than from `process.env` directly inside the component.

### Step 1: Create PreviewWrapper.tsx

Create `app/components/PreviewWrapper.tsx`:

```ts
// app/components/PreviewWrapper.tsx
import { useRevalidator } from '@remix-run/react';
import { useEffect, useState } from 'react';
import type { ComponentType, ReactNode } from 'react';

interface PreviewWrapperProps {
  children: ReactNode;
}

export function PreviewWrapper({ children }: PreviewWrapperProps) {
  const revalidator = useRevalidator();
  const [PreviewComponent, setPreviewComponent] = useState<ComponentType<any> | null>(null);

  useEffect(() => {
    if (typeof window === 'undefined') return;

    import('@hygraph/preview-sdk/react')
      .then((mod) => setPreviewComponent(() => mod.HygraphPreview))
      .catch((error) => {
        console.error('Failed to load Hygraph Preview SDK:', error);
      });
  }, []);

  if (!PreviewComponent || typeof window === 'undefined') {
    return <>{children}</>;
  }

  return (
    <PreviewComponent
      endpoint={window.ENV?.HYGRAPH_ENDPOINT}
      studioUrl={window.ENV?.HYGRAPH_STUDIO_URL}
      debug={true}  // Optional: Enable console logging
      mode="iframe"  // Optional: 'iframe' | 'standalone' | 'auto'
      onSave={() => {  // Optional: Custom save handler
        console.log('Content saved, refreshing...');
        revalidator.revalidate();
      }}
      overlay={{  // Optional: Customize overlay styling
        style: {
          borderColor: '#3b82f6',
          borderWidth: '2px',
        },
        button: {
          backgroundColor: '#3b82f6',
          color: 'white',
        },
      }}
      sync={{
        fieldFocus: true,  // Optional: Enable field focus sync from Studio
        fieldUpdate: false,  // Optional: Apply live field updates to Preview
      }}
    >
      {children}
    </PreviewComponent>
  );
}
```

### Step 2: Expose environment variables and register PreviewWrapper in root.tsx

Remix keeps server environment variables server-side by default. Expose the ones the SDK needs to the browser with a root `loader` and an inline script, then wrap `<Outlet />` with `PreviewWrapper` inside `<body>`.

```ts
// app/root.tsx
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useLoaderData,
} from '@remix-run/react';
import type { LoaderFunctionArgs } from '@remix-run/node';
import { json } from '@remix-run/node';
import { PreviewWrapper } from './components/PreviewWrapper';

export async function loader({}: LoaderFunctionArgs) {
  return json({
    ENV: {
      HYGRAPH_ENDPOINT: process.env.HYGRAPH_ENDPOINT,
      HYGRAPH_STUDIO_URL: process.env.HYGRAPH_STUDIO_URL,
    },
  });
}

export default function App() {
  const { ENV } = useLoaderData<typeof loader>();

  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
        <script
          dangerouslySetInnerHTML={{
            __html: `window.ENV = ${JSON.stringify(ENV)}`,
          }}
        />
      </head>
      <body>
        <PreviewWrapper>
          <Outlet />
        </PreviewWrapper>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}
```

If the wrapper is absent from `root.tsx`, or the `window.ENV` script runs after `PreviewWrapper` reads it, the SDK cannot register page content and Click to Edit will not work.

**Configuration properties**

| Property              | Required / Optional | Description |
|-----------------------|----------------------|-------------|
| `endpoint`            | **Required**         | Hygraph Content API endpoint. To learn how to retrieve the Content API endpoint, see [our docs](/docs/developer-guides/project/api-access#content-api). |
| `studioUrl`           | Optional (recommended) | Studio base URL. Defaults to `https://app.hygraph.com`. Set this if your Studio runs on a regional or custom domain. |
| `debug`               | Optional             | Enables verbose console logs to diagnose attribute issues. |
| `mode`                | Optional             | Forces a specific mode. Options: `'iframe'` \| `'standalone'` \| `'auto'`. Auto-detection works for most cases. |
| `onSave`              | Optional             | Runs after Hygraph reports a save and receives the entry ID for targeted revalidation. |
| `overlay`             | Optional             | Customize overlay border and button appearance. |
| `sync.fieldFocus`     | Optional             | Synchronizes field focus between Studio and the preview when an editor selects a field. |
| `sync.fieldUpdate`    | Optional             | Updates the preview immediately when field updates happen in Studio. Defaults to `false`. |
| `allowedOrigins`      | Optional             | Extends the list of domains that can host your preview iframe. Example: For shared preview environments (QA, staging), add the base URL here. |

## Set environment variables

Add the following to `.env` in your project's root directory. If you already have these from live preview setup, skip this step.

```bash
# .env
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token  # Optional: Required if your project uses authentication
```

Remix has no client-exposure convention like Next.js's `NEXT_PUBLIC_` prefix. Every value the browser needs, such as `HYGRAPH_ENDPOINT` and `HYGRAPH_STUDIO_URL`, must be passed through a loader and injected into `window.ENV`, as shown in [Step 2](#step-2-expose-environment-variables-and-register-previewwrapper-in-roottsx) above.

**Content API endpoint**: Find this under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our documentation on the [Content API](/docs/developer-guides/project/api-access#content-api).

**Hygraph Studio base URL**: Copy from your browser's address bar in Studio. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.

**Permanent Auth Token**: Create under **Project Settings > Access > Permanent Auth Tokens**. Set the default content stage to **DRAFT**. Only required if your project enforces authentication on Content API requests. For more information, see our dedicated documentation on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).

## Add data attributes to content elements

Data attributes (`data-hygraph-*`) connect your rendered elements to specific Hygraph fields. The SDK reads these attributes and attaches Edit overlays automatically. The same attributes work for variants; no additional instrumentation is required. For the full attribute reference, see [Add data attributes to content elements](/docs/developer-guides/schema/click-to-edit#add-data-attributes-to-content-elements).

The examples below use a recipe model. To bootstrap the same Hygraph project used here, follow the <Link href="https://github.com/hygraph/preview-sdk/blob/main/examples/project-setup/README.md" target="_blank">project setup instructions</Link>.

Remix fetches the entry with a route `loader` and reads it with `useLoaderData()`. The route id comes from `params` in the loader, not a hook called inside the component.

```ts
// app/routes/recipes.$id.tsx
import { json, type LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';

export async function loader({ params }: LoaderFunctionArgs) {
  const { id } = params;

  if (!id) {
    throw new Response('Recipe not found', { status: 404 });
  }

  const recipe = await getRecipe(id);

  if (!recipe) {
    throw new Response('Recipe not found', { status: 404 });
  }

  return json({ recipe });
}

export default function RecipePage() {
  const { recipe } = useLoaderData<typeof loader>();
  // ... rendered below
}
```

### Simple fields

Add `data-hygraph-entry-id` and `data-hygraph-field-api-id` to any element rendering a Hygraph field value.

```ts

// app/routes/recipes.$id.tsx

  return (
    <main>
      {/* Title */}
      <h1
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="title"
      >
        {recipe.title}
      </h1>

      {/* Description */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="description"
        data-hygraph-rich-text-format="html"
      >
        <div dangerouslySetInnerHTML={{ __html: recipe.description.html }} />
      </div>

      {/* Recipe Meta */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="prepTime"
      >
        {recipe.prepTime}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="cookTime"
      >
        {recipe.cookTime}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="servings"
      >
        {recipe.servings}
      </div>

      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="difficulty"
      >
        {recipe.difficulty}
      </div>

      {/* Hero Image */}
      <div
        data-hygraph-entry-id={recipe.id}
        data-hygraph-field-api-id="heroImage"
      >
        {/* Example image rendering */}
        {recipe.heroImage?.url && (
          <img src={recipe.heroImage.url} alt={recipe.title} />
        )}
      </div>
    </main>
  );
```

### Component fields

Components require the `data-hygraph-component-chain` attribute so Studio can navigate to the correct nested field instance. Use the helper functions from `@hygraph/preview-sdk/core`:

```ts
import {
  createComponentChainLink,
  createPreviewAttributes,
  withFieldPath,
} from '@hygraph/preview-sdk/core';
```

The `instanceId` in each chain link is the `id` field of the component instance returned in your GraphQL query. It is not the component type's API ID. Query for `id` on every component you want to instrument. See the GraphQL example in [Basic components](#basic-components) below.

#### Basic components

These are direct children of the Recipe model, and are not nested inside other components. Each one uses a single-link chain.

<Tabs>
  <TabsItem label="Ingredients">

```ts

// Type: Basic component
// Structure: `Recipe → ingredients[] → ingredient fields`
// Used for: `quantity`, `unit` fields
// Path depth: 1 level (Recipe → Ingredient)
// Chain link: 1

// app/routes/recipes.$id.tsx

{recipe.ingredients.map((ingredient, index) => {
  const chain = [createComponentChainLink('ingredients', ingredient.id)];
  const basePath = `ingredients.${index}`;
  const quantityAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'quantity',
      componentChain: chain,
    }),
    `${basePath}.quantity`
  );
  // ... used for quantity, unit fields
})}
```

  </TabsItem>
  <TabsItem label="Recipe steps">

```ts

// Type: Basic component
// Structure: `Recipe → recipeSteps[] → step fields`
// Used for: `stepNumber`, `title`, `instruction`, `estimatedTime`
// Path depth: 1 level (Recipe → Recipe Step)
// Chain link: 1

// app/routes/recipes.$id.tsx

{recipe.recipeSteps.map((step, index) => {
  const chain = [createComponentChainLink('recipeSteps', step.id)];
  const stepBasePath = `recipeSteps.${index}`;
  const stepNumberAttributes = withFieldPath(
    createPreviewAttributes({
      entryId: recipe.id,
      fieldApiId: 'stepNumber',
      componentChain: chain,
    }),
    `${stepBasePath}.stepNumber`
  );
  // ... used for stepNumber, title, instruction, estimatedTime
})}
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for basic components:

```graphql
query GetRecipe($id: ID!) {
  recipe(where: { id: $id }, stage: DRAFT) {
    id
    title
    ingredients {
      id        # instanceId for the ingredient component
      quantity
      unit
    }
    recipeSteps {
      id        # instanceId for the step component
      stepNumber
      instruction { html }
    }
  }
}
```

#### Nested components

Nested components require a multi-link chain, ordered from the outermost to the innermost component.

<Tabs>
  <TabsItem label="Equipment within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → equipment[] → equipment fields`
// Used for: `name`, `required`, `alternatives`, `notes` fields
// Path depth: 2 levels (Recipe → Recipe Step → Equipment)
// Chain links: 2

// app/routes/recipes.$id.tsx

{step.equipment.map((equip, equipIndex) => {
  const equipChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('equipment', equip.id)
  ];
  const equipBasePath = `${stepBasePath}.equipment.${equipIndex}`;
  // ... used for name, required, alternatives, notes fields
})}
```

  </TabsItem>
  <TabsItem label="Ingredients used within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → ingredientsUsed[] → ingredient fields`
// Used for: `ingredientName`, `preparation`, `timing`, `notes` fields
// Path depth: 2 levels (Recipe → Recipe Step → Ingredient Reference)
// Chain links: 2

// app/routes/recipes.$id.tsx

{step.ingredientsUsed.map((ingred, ingredIndex) => {
  const ingredChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('ingredientsUsed', ingred.id)
  ];
  const ingredBasePath = `${stepBasePath}.ingredientsUsed.${ingredIndex}`;
  // ... used for ingredientName, preparation, timing, notes fields
})}
```

  </TabsItem>
  <TabsItem label="Tips within recipe steps">

```ts

// Type: Nested component
// Structure: `Recipe → recipeSteps[] → tips[] → tip fields`
// Used for: `icon`, `title`, `content` fields
// Path depth: 2 levels (Recipe → Recipe Step → Tip)
// Chain links: 2

// app/routes/recipes.$id.tsx

{step.tips.map((tip, tipIndex) => {
  const tipChain = [
    createComponentChainLink('recipeSteps', step.id),
    createComponentChainLink('tips', tip.id)
  ];
  const tipBasePath = `${stepBasePath}.tips.${tipIndex}`;
  // ... used for icon, title, content fields
})}
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for nested components. Extend your basic component query:

```graphql
recipeSteps {
  id
  stepNumber
  instruction { html }
  equipment {
    id        # instanceId for nested equipment
    name
    required
  }
  tips {
    id        # instanceId for nested tips
    title
    content { html }
  }
}
```

#### Modular components

Modular components can be one of several types. Use `__typename` to branch and build the chain per type.

The examples below display aliased GraphQL fields such as `section.tipTitle` and `section.tipContent`. Those come from query aliases (`tipTitle: title`, `tipContent: content`). `fieldApiId` must still use the schema API IDs (`title`, `content`).

<Tabs>
  <TabsItem label="Featured Content">

```ts

// Type: Modular component
// Structure: `Recipe → featuredContent (ProTip | VideoEmbed | IngredientSpotlight)`
// Used for: Single featured content section
// Path depth: 1 level
// Chain link: 1

// app/routes/recipes.$id.tsx

// Chain creation
const section = recipe.featuredContent;
const chain = [createComponentChainLink('featuredContent', section.id)];
const basePath = 'featuredContent';

// Switch
switch (section.__typename) {
  case 'ProTip': {
    const proTipIconAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'icon',
        componentChain: chain,
      }),
      `${basePath}.icon`
    );
    const proTipTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'title',
        componentChain: chain,
      }),
      `${basePath}.title`
    );
    const proTipContentAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'content',
        componentChain: chain,
      }),
      `${basePath}.content`
    );

    return (
      <div>
        <div {...proTipIconAttributes}>
          {section.icon || '⭐'}
        </div>
        <h3 {...proTipTitleAttributes}>
          {section.tipTitle}
        </h3>
        <div
          dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
          {...proTipContentAttributes}
          data-hygraph-rich-text-format="html"
        />
      </div>
    );
  }

  case 'VideoEmbed': {
    const videoTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'title',
        componentChain: chain,
      }),
      `${basePath}.title`
    );
    const videoUrlAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'videoUrl',
        componentChain: chain,
      }),
      `${basePath}.videoUrl`
    );
    const videoDescriptionAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'description',
        componentChain: chain,
      }),
      `${basePath}.description`
    );

    return (
      <div>
        <h3 {...videoTitleAttributes}>
          {section.videoTitle}
        </h3>
        <div {...videoUrlAttributes}>
          {/* Video embed logic */}
        </div>
        {section.videoDescription && (
          <div
            dangerouslySetInnerHTML={{ __html: section.videoDescription.html }}
            {...videoDescriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
        )}
      </div>
    );
  }

  case 'IngredientSpotlight': {
    const spotlightImageAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'image',
        componentChain: chain,
      }),
      `${basePath}.image`
    );
    const spotlightTitleAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'ingredient',
        componentChain: chain,
      }),
      `${basePath}.ingredient`
    );
    const spotlightDescriptionAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'description',
        componentChain: chain,
      }),
      `${basePath}.description`
    );
    const spotlightSubstitutesAttributes = withFieldPath(
      createPreviewAttributes({
        entryId: recipe.id,
        fieldApiId: 'substitutes',
        componentChain: chain,
      }),
      `${basePath}.substitutes`
    );

    return (
      <div>
        <div {...spotlightImageAttributes}>
          {section.ingredientImage ? (
            <img
              src={section.ingredientImage.url}
              alt={section.ingredient?.name || 'Ingredient'}
              width={120}
              height={120}
            />
          ) : (
            <div>🌿</div>
          )}
        </div>
        <h3 {...spotlightTitleAttributes}>
          Star Ingredient: <span>{section.ingredient?.name || 'Unknown'}</span>
        </h3>
        <div
          dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
          {...spotlightDescriptionAttributes}
          data-hygraph-rich-text-format="html"
        />
        {section.substitutes && (
          <span {...spotlightSubstitutesAttributes}>
            {section.substitutes}
          </span>
        )}
      </div>
    );
  }

  default:
    return null;
}
```

  </TabsItem>
  <TabsItem label="Additional Sections">

```ts

// Type: Modular component
// Structure: `Recipe → additionalSections[] (ProTip | VideoEmbed | IngredientSpotlight)[]`
// Used for: Multiple additional content sections
// Path depth: 1 level
// Chain link: 1

// app/routes/recipes.$id.tsx

{recipe.additionalSections.map((section, index) => {
  // Chain creation
  const chain = [createComponentChainLink('additionalSections', section.id)];
  const basePath = `additionalSections.${index}`;

  // Switch
  switch (section.__typename) {
    case 'ProTip': {
      const proTipListIconAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'icon',
          componentChain: chain,
        }),
        `${basePath}.icon`
      );
      const proTipListTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const proTipListContentAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'content',
          componentChain: chain,
        }),
        `${basePath}.content`
      );

      return (
        <div key={section.id}>
          <div {...proTipListIconAttributes}>
            {section.icon || '💡'}
          </div>
          <h3 {...proTipListTitleAttributes}>
            {section.tipTitle}
          </h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
            {...proTipListContentAttributes}
            data-hygraph-rich-text-format="html"
          />
        </div>
      );
    }

    case 'VideoEmbed': {
      const listVideoTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: chain,
        }),
        `${basePath}.title`
      );
      const listVideoUrlAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'videoUrl',
          componentChain: chain,
        }),
        `${basePath}.videoUrl`
      );
      const listVideoDescriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );

      return (
        <div key={section.id}>
          <h3 {...listVideoTitleAttributes}>
            {section.videoTitle}
          </h3>
          <div {...listVideoUrlAttributes}>
            {/* Video embed logic */}
          </div>
          {section.videoDescription && (
            <div
              dangerouslySetInnerHTML={{ __html: section.videoDescription.html }}
              {...listVideoDescriptionAttributes}
              data-hygraph-rich-text-format="html"
            />
          )}
        </div>
      );
    }

    case 'IngredientSpotlight': {
      const listSpotlightImageAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'image',
          componentChain: chain,
        }),
        `${basePath}.image`
      );
      const listSpotlightTitleAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'ingredient',
          componentChain: chain,
        }),
        `${basePath}.ingredient`
      );
      const listSpotlightDescriptionAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'description',
          componentChain: chain,
        }),
        `${basePath}.description`
      );
      const listSpotlightSubstitutesAttributes = withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'substitutes',
          componentChain: chain,
        }),
        `${basePath}.substitutes`
      );

      return (
        <div key={section.id}>
          <div {...listSpotlightImageAttributes}>
            {section.ingredientImage ? (
              <img
                src={section.ingredientImage.url}
                alt={section.ingredient?.name || 'Ingredient'}
                width={80}
                height={80}
              />
            ) : (
              <div>🥬</div>
            )}
          </div>
          <h3 {...listSpotlightTitleAttributes}>
            Featured: <span>{section.ingredient?.name || 'Unknown'}</span>
          </h3>
          <div
            dangerouslySetInnerHTML={{ __html: section.ingredientDescription.html }}
            {...listSpotlightDescriptionAttributes}
            data-hygraph-rich-text-format="html"
          />
          {section.substitutes && (
            <span {...listSpotlightSubstitutesAttributes}>
              {section.substitutes}
            </span>
          )}
        </div>
      );
    }

    default:
      return null;
  }
})}
```

  </TabsItem>
</Tabs>

### Full example

```ts

// app/routes/recipes.$id.tsx

import { json, type LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { createComponentChainLink, createPreviewAttributes, withFieldPath } from '@hygraph/preview-sdk/core';

export async function loader({ params }: LoaderFunctionArgs) {
  const { id } = params;

  if (!id) {
    throw new Response('Recipe not found', { status: 404 });
  }

  const recipe = await getRecipe(id);

  if (!recipe) {
    throw new Response('Recipe not found', { status: 404 });
  }

  return json({ recipe });
}

export default function RecipePage() {
  const { recipe } = useLoaderData<typeof loader>();

  return (
    <main>
      {/* Basic fields */}

      <h1 data-hygraph-field-api-id="title" data-hygraph-entry-id={recipe.id}>
        {recipe.title}
      </h1>

      <div
        data-hygraph-field-api-id="description"
        data-hygraph-entry-id={recipe.id}
        data-hygraph-rich-text-format="html"
      >
        <div dangerouslySetInnerHTML={{ __html: recipe.description.html }} />
      </div>

      <div data-hygraph-field-api-id="prepTime" data-hygraph-entry-id={recipe.id}>
        {recipe.prepTime}min
      </div>

      <div data-hygraph-entry-id={recipe.id} data-hygraph-field-api-id="categories">
        {recipe.categories.map((category) => (
          <span key={category.id}>{category.name}</span>
        ))}
      </div>

      {/* Basic components */}

      {/* Ingredients */}
      {recipe.ingredients.map((ingredient, index) => {
        const chain = [createComponentChainLink('ingredients', ingredient.id)];
        const basePath = `ingredients.${index}`;

        const quantityAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'quantity',
            componentChain: chain,
          }),
          `${basePath}.quantity`
        );

        const unitAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'unit',
            componentChain: chain,
          }),
          `${basePath}.unit`
        );

        return (
          <div key={ingredient.id}>
            <span>{ingredient.ingredient?.name}</span>
            <span {...quantityAttributes}>{ingredient.quantity}</span>
            <span {...unitAttributes}>{ingredient.unit}</span>
          </div>
        );
      })}

      {/* Recipe Steps (with nested equipment) */}
      {recipe.recipeSteps.map((step, index) => {
        const chain = [createComponentChainLink('recipeSteps', step.id)];
        const stepBasePath = `recipeSteps.${index}`;

        const stepNumberAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'stepNumber',
            componentChain: chain,
          }),
          `${stepBasePath}.stepNumber`
        );

        const stepTitleAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: chain,
          }),
          `${stepBasePath}.title`
        );

        const instructionAttributes = withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'instruction',
            componentChain: chain,
          }),
          `${stepBasePath}.instruction`
        );

        return (
          <div key={step.id}>
            <span {...stepNumberAttributes}>{step.stepNumber}</span>
            {step.title && <h3 {...stepTitleAttributes}>{step.title}</h3>}
            <div
              dangerouslySetInnerHTML={{ __html: step.instruction.html }}
              {...instructionAttributes}
              data-hygraph-rich-text-format="html"
            />

            {/* Nested: Equipment within Recipe Steps */}
            {step.equipment?.map((equip, equipIndex) => {
              const equipChain = [
                createComponentChainLink('recipeSteps', step.id),
                createComponentChainLink('equipment', equip.id),
              ];
              const equipBasePath = `${stepBasePath}.equipment.${equipIndex}`;

              const nameAttributes = withFieldPath(
                createPreviewAttributes({
                  entryId: recipe.id,
                  fieldApiId: 'name',
                  componentChain: equipChain,
                }),
                `${equipBasePath}.name`
              );

              const requiredAttributes = withFieldPath(
                createPreviewAttributes({
                  entryId: recipe.id,
                  fieldApiId: 'required',
                  componentChain: equipChain,
                }),
                `${equipBasePath}.required`
              );

              return (
                <div key={equip.id}>
                  <span {...nameAttributes}>{equip.name}</span>
                  {equip.required && <span {...requiredAttributes}>Required</span>}
                </div>
              );
            })}
          </div>
        );
      })}

      {/* Modular components */}

      {/* Featured Content (Single) */}
      {recipe.featuredContent && (() => {
        const section = recipe.featuredContent;
        const chain = [createComponentChainLink('featuredContent', section.id)];
        const basePath = 'featuredContent';

        switch (section.__typename) {
          case 'ProTip': {
            const iconAttributes = withFieldPath(
              createPreviewAttributes({
                entryId: recipe.id,
                fieldApiId: 'icon',
                componentChain: chain,
              }),
              `${basePath}.icon`
            );
            const titleAttributes = withFieldPath(
              createPreviewAttributes({
                entryId: recipe.id,
                fieldApiId: 'title',
                componentChain: chain,
              }),
              `${basePath}.title`
            );
            const contentAttributes = withFieldPath(
              createPreviewAttributes({
                entryId: recipe.id,
                fieldApiId: 'content',
                componentChain: chain,
              }),
              `${basePath}.content`
            );

            return (
              <div>
                <div {...iconAttributes}>{section.icon}</div>
                <h3 {...titleAttributes}>{section.tipTitle}</h3>
                <div
                  dangerouslySetInnerHTML={{ __html: section.tipContent.html }}
                  {...contentAttributes}
                  data-hygraph-rich-text-format="html"
                />
              </div>
            );
          }

          default:
            return null;
        }
      })()}
    </main>
  );
}
```

## Verify the setup

1. Open an entry in Studio for the model you configured.
2. In the right sidebar, click **Open live preview**. The preview should load alongside the entry form.
3. Hover over an element you tagged with `data-hygraph-*` attributes. An **Edit** button should appear.
4. Click **Edit**. Studio should scroll to and focus the corresponding field in the entry form.
5. Edit the field value and click **Save & Preview**. The preview should refresh and show the updated content.

If you are working with variants, no additional setup is required. Clicking a tagged element while a variant is open focuses the field directly in the variant overlay.

If the **Edit** button does not appear at step 3, add `debug={true}` to your `PreviewComponent` and check the browser console for missing attribute warnings. Also confirm `window.ENV` is populated: check the browser console for `window.ENV` and verify it contains your endpoint and Studio URL. For component fields, confirm your GraphQL query includes the `id` field on each component and that the `instanceId` values in your chain match what the query returns. For more information, see [Troubleshooting](/docs/developer-guides/schema/click-to-edit#troubleshooting).

## Related docs

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): General setup steps, attribute reference, Studio widget configuration, and troubleshooting.
- [Click to Edit - Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api): React hooks, Preview methods, DOM events, and helpers for dynamic content.
- [Live preview setup](/docs/developer-guides/schema/live-preview): Configure the Studio preview iframe before deploying Click to Edit to editors.


---
# Click to Edit - Vanilla JavaScript

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit-vanilla-js

This page walks through implementing Click to Edit in a server-rendered vanilla JavaScript project using the <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Hygraph Preview SDK</Link>. By the end, editors can click any instrumented element in the preview to jump directly to that field in Studio.

For the general setup overview and configuration reference, see [Click to Edit setup](/docs/developer-guides/schema/click-to-edit). Examples for other supported frameworks are available at:
- [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router)
- [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router)
- [Remix](/docs/developer-guides/schema/click-to-edit-remix)
- [Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt)
- [Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api)

<Alert theme="info">
If you are instrumenting a frontend you did not build from scratch, start by initializing `Preview` on a page with a single simple field. Confirm the Edit button appears and the save refresh works before adding component attributes. Components require additional data from your GraphQL queries.
</Alert>

## Steps

1. [Install the Preview SDK](#install-the-preview-sdk).
2. [Make the SDK available in the browser](#make-the-sdk-available-in-the-browser).
3. [Set environment variables](#set-environment-variables).
4. [Add data attributes to your content elements](#add-data-attributes-to-content-elements).
5. [Set up the Preview widget in Studio](/docs/developer-guides/schema/click-to-edit#set-up-the-preview-widget-in-studio).
6. [Verify the setup](#verify-the-setup).

## Install the Preview SDK

To install the Preview SDK, run the following command:

```bash
npm install @hygraph/preview-sdk
```

## Make the SDK available in the browser

Without a bundler, the browser cannot resolve `import '@hygraph/preview-sdk'`. Copy the package's prebuilt UMD bundle into a static directory your server exposes, and load it with a plain `<script>` tag.

<Alert theme="info">
There is no framework wrapper component for vanilla JavaScript. The SDK ships a UMD build you serve as a static file and initialize directly with a `<script>` tag. You can also load the same UMD build from a CDN such as <Link href="https://unpkg.com/@hygraph/preview-sdk/dist/index.umd.js" target="_blank">unpkg</Link>.
</Alert>

### Step 1: Copy the UMD bundle

Add a setup script that copies the bundle from `node_modules` into a folder your server serves statically:

```js
// setup.js
import { promises as fs } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';

const __dirname = dirname(fileURLToPath(import.meta.url));

async function setup() {
  const jsDir = join(__dirname, 'js');
  await fs.mkdir(jsDir, { recursive: true });

  const srcPath = join(__dirname, 'node_modules', '@hygraph', 'preview-sdk', 'dist', 'index.umd.js');
  const destPath = join(jsDir, 'preview-sdk.js');

  await fs.copyFile(srcPath, destPath);
  console.log('Preview SDK UMD bundle copied to js/preview-sdk.js');
}

setup();
```

Run it after every `npm install`, for example with a `postinstall` or `predev` script in `package.json`:

```json
{
  "scripts": {
    "setup": "node setup.js",
    "dev": "npm run setup && node server.js"
  }
}
```

### Step 2: Serve the bundle and initialize Preview

Serve the `js/` directory as static files, then include the bundle and initialize `Preview` in the page you render:

```js
// server.js
import express from 'express';
import { join } from 'path';

const app = express();
app.use('/js', express.static(join(process.cwd(), 'js')));
```

```html
<!-- rendered page -->
<script src="/js/preview-sdk.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    if (window.HygraphPreviewSDK && window.HygraphPreviewSDK.Preview) {
      const preview = new window.HygraphPreviewSDK.Preview({
        endpoint: '__HYGRAPH_ENDPOINT__',
        studioUrl: '__HYGRAPH_STUDIO_URL__',
        debug: true, // Optional: Enable console logging
        mode: 'iframe', // Optional: 'iframe' | 'standalone' | 'auto'
        overlayEnabled: true, // Optional: Set to false to disable overlays entirely
        overlay: { // Optional: Customize overlay styling
          style: {
            borderColor: '#3b82f6',
            borderWidth: '2px',
          },
          button: {
            backgroundColor: '#3b82f6',
            color: 'white',
          },
        },
        sync: {
          fieldFocus: true, // Optional: Enable field focus sync from Studio
          fieldUpdate: false, // Optional: Apply live field updates to Preview
        },
      });

      // Refresh on save. The core class has no `onSave` constructor
      // option; subscribe to the save event instead.
      preview.subscribe('save', {
        callback: () => {
          console.log('Content saved, refreshing...');
          window.location.reload();
        },
      });

      window.addEventListener('beforeunload', () => {
        preview.destroy();
      });

      console.log('Live Preview initialized', preview.getVersion());
    } else {
      console.error('Live Preview not loaded');
    }
  });
</script>
```

Replace `__HYGRAPH_ENDPOINT__` and `__HYGRAPH_STUDIO_URL__` with values interpolated from your server-side configuration, as shown in [Set environment variables](#set-environment-variables) below. If the script tag or the `Preview` initialization is missing from a page, the SDK cannot register that page's content and Click to Edit will not work on it.

**Configuration properties**

| Property              | Required / Optional | Description |
|-----------------------|----------------------|-------------|
| `endpoint`            | **Required**         | Hygraph Content API endpoint. To learn how to retrieve the Content API endpoint, see [our docs](/docs/developer-guides/project/api-access#content-api). |
| `studioUrl`           | Optional (recommended) | Studio base URL. Defaults to `https://app.hygraph.com`. Set this if your Studio runs on a regional or custom domain. |
| `debug`               | Optional             | Enables verbose console logs to diagnose attribute issues. |
| `mode`                | Optional             | Forces a specific mode. Options: `'iframe'` \| `'standalone'` \| `'auto'`. Auto-detection works for most cases. |
| `overlayEnabled`      | Optional             | Set to `false` to disable hover overlays and Edit buttons entirely, while keeping the SDK's Studio connection active. Defaults to `true`. |
| `overlay`             | Optional             | Customize overlay border and button appearance. |
| `sync.fieldFocus`     | Optional             | Synchronizes field focus between Studio and the preview when an editor selects a field. |
| `sync.fieldUpdate`    | Optional             | Updates the preview immediately when field updates happen in Studio. Defaults to `false`. |
| `allowedOrigins`      | Optional             | Extends the list of domains that can host your preview iframe. Example: For shared preview environments (QA, staging), add the base URL here. |

The core `Preview` class has no `onSave` constructor option. Use `preview.subscribe('save', { callback })` to react to saves.

## Set environment variables

The server reads configuration from Node's `process.env` when it renders each page. Set the following on your host, or in a `.env` file loaded by your process manager:

```bash
# .env
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token  # Optional: Required if your project uses authentication
```

```js
// server.js
const CONFIG = {
  HYGRAPH_ENDPOINT: process.env.HYGRAPH_ENDPOINT,
  HYGRAPH_STUDIO_URL: process.env.HYGRAPH_STUDIO_URL,
  HYGRAPH_TOKEN: process.env.HYGRAPH_TOKEN || '',
};
```

Interpolate `CONFIG.HYGRAPH_ENDPOINT` and `CONFIG.HYGRAPH_STUDIO_URL` into the inline `<script>` that initializes `Preview`, as shown in [Step 2](#step-2-serve-the-bundle-and-initialize-preview) above.

**Content API endpoint**: Find this under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our documentation on the [Content API](/docs/developer-guides/project/api-access#content-api).

**Hygraph Studio base URL**: Copy from your browser's address bar in Studio. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.

**Permanent Auth Token**: Create under **Project Settings > Access > Permanent Auth Tokens**. Set the default content stage to **DRAFT**. Only required if your project enforces authentication on Content API requests. For more information, see our dedicated documentation on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).

## Add data attributes to content elements

Data attributes (`data-hygraph-*`) connect your rendered elements to specific Hygraph fields. The SDK reads these attributes and attaches Edit overlays automatically. The same attributes work for variants; no additional instrumentation is required. For the full attribute reference, see [Add data attributes to content elements](/docs/developer-guides/schema/click-to-edit#add-data-attributes-to-content-elements).

The examples below use a recipe model. To bootstrap the same Hygraph project used here, follow the <Link href="https://github.com/hygraph/preview-sdk/blob/main/examples/project-setup/README.md" target="_blank">project setup instructions</Link>.

A server without a templating engine has no JSX or component-chain helper calls available at render time. Build the `data-hygraph-*` attributes as plain strings inside your HTML template literals, and encode `data-hygraph-component-chain` as a JSON string with `JSON.stringify`.

### Simple fields

Add `data-hygraph-entry-id` and `data-hygraph-field-api-id` to any HTML element rendering a Hygraph field value.

```js

// server.js

const html = `
  <main>
    <h1 data-hygraph-field-api-id="title" data-hygraph-entry-id="${recipe.id}">
      ${recipe.title}
    </h1>

    <div
      data-hygraph-field-api-id="description"
      data-hygraph-entry-id="${recipe.id}"
      data-hygraph-rich-text-format="html"
    >
      ${recipe.description.html}
    </div>

    <div data-hygraph-field-api-id="prepTime" data-hygraph-entry-id="${recipe.id}">
      ${recipe.prepTime}min
    </div>

    <div data-hygraph-field-api-id="cookTime" data-hygraph-entry-id="${recipe.id}">
      ${recipe.cookTime}min
    </div>

    <div data-hygraph-field-api-id="servings" data-hygraph-entry-id="${recipe.id}">
      ${recipe.servings}
    </div>

    <div data-hygraph-field-api-id="difficulty" data-hygraph-entry-id="${recipe.id}">
      ${recipe.difficulty}
    </div>

    <div data-hygraph-field-api-id="heroImage" data-hygraph-entry-id="${recipe.id}">
      ${recipe.heroImage?.url ? `<img src="${recipe.heroImage.url}" alt="${recipe.title}" />` : ''}
    </div>
  </main>
`;
```

### Component fields

Components require the `data-hygraph-component-chain` attribute so Studio can navigate to the correct nested field instance. Without helper functions, build the chain as a plain array and encode it with `JSON.stringify`:

```js
const componentChain = JSON.stringify([
  { fieldApiId: 'ingredients', instanceId: ingredient.id },
]);
```

The `instanceId` in each chain link is the `id` field of the component instance returned in your GraphQL query. It is not the component type's API ID. Query for `id` on every component you want to instrument. See the GraphQL example in [Basic components](#basic-components) below.

<Alert theme="info">
If your server uses a template engine that supports importing functions (for example, EJS or a Node script that imports ES modules), you can use `createComponentChainLink`, `createPreviewAttributes`, and `withFieldPath` from `@hygraph/preview-sdk/core` instead of building attribute strings by hand. Both approaches produce identical HTML.
</Alert>

#### Basic components

These are direct children of the Recipe model, and are not nested inside other components. Each one uses a single-link chain.

<Tabs>
  <TabsItem label="Ingredients">

```js

// Type: Basic component
// Structure: Recipe → ingredients[] → ingredient fields
// Used for: quantity, unit fields
// Path depth: 1 level (Recipe → Ingredient)
// Chain link: 1

// server.js

const ingredientsHtml = recipe.ingredients.map((ingredient) => {
  const chain = JSON.stringify([{ fieldApiId: 'ingredients', instanceId: ingredient.id }]);

  return `
    <div>
      <span>${ingredient.ingredient?.name ?? ''}</span>
      <span
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="quantity"
        data-hygraph-component-chain='${chain}'
      >${ingredient.quantity}</span>
      <span
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="unit"
        data-hygraph-component-chain='${chain}'
      >${ingredient.unit}</span>
    </div>
  `;
}).join('');
```

  </TabsItem>
  <TabsItem label="Recipe steps">

```js

// Type: Basic component
// Structure: Recipe → recipeSteps[] → step fields
// Used for: stepNumber, title, instruction, estimatedTime
// Path depth: 1 level (Recipe → Recipe Step)
// Chain link: 1

// server.js

const stepsHtml = recipe.recipeSteps.map((step) => {
  const chain = JSON.stringify([{ fieldApiId: 'recipeSteps', instanceId: step.id }]);

  return `
    <div>
      <span
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="stepNumber"
        data-hygraph-component-chain='${chain}'
      >${step.stepNumber}</span>
      ${step.title ? `<h3
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="title"
        data-hygraph-component-chain='${chain}'
      >${step.title}</h3>` : ''}
      <div
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="instruction"
        data-hygraph-component-chain='${chain}'
        data-hygraph-rich-text-format="html"
      >${step.instruction.html}</div>
    </div>
  `;
}).join('');
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for basic components:

```graphql
query GetRecipe($id: ID!) {
  recipe(where: { id: $id }, stage: DRAFT) {
    id
    title
    ingredients {
      id        # instanceId for the ingredient component
      quantity
      unit
    }
    recipeSteps {
      id        # instanceId for the step component
      stepNumber
      instruction { html }
    }
  }
}
```

#### Nested components

Nested components require a multi-link chain, ordered from the outermost to the innermost component.

<Tabs>
  <TabsItem label="Equipment within recipe steps">

```js

// Type: Nested component
// Structure: Recipe → recipeSteps[] → equipment[] → equipment fields
// Used for: name, required, alternatives, notes fields
// Path depth: 2 levels (Recipe → Recipe Step → Equipment)
// Chain links: 2

// server.js

const equipmentHtml = (step.equipment || []).map((equip) => {
  const chain = JSON.stringify([
    { fieldApiId: 'recipeSteps', instanceId: step.id },
    { fieldApiId: 'equipment', instanceId: equip.id },
  ]);

  return `
    <div>
      <span
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="name"
        data-hygraph-component-chain='${chain}'
      >${equip.name}</span>
      ${equip.required ? `<span
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="required"
        data-hygraph-component-chain='${chain}'
      >Required</span>` : ''}
    </div>
  `;
}).join('');
```

  </TabsItem>
  <TabsItem label="Ingredients used within recipe steps">

```js

// Type: Nested component
// Structure: Recipe → recipeSteps[] → ingredientsUsed[] → ingredient fields
// Used for: ingredientName, preparation, timing, notes fields
// Path depth: 2 levels (Recipe → Recipe Step → Ingredient Reference)
// Chain links: 2

// server.js

const ingredientsUsedHtml = (step.ingredientsUsed || []).map((ingred) => {
  const chain = JSON.stringify([
    { fieldApiId: 'recipeSteps', instanceId: step.id },
    { fieldApiId: 'ingredientsUsed', instanceId: ingred.id },
  ]);

  return `
    <div>
      <span
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="ingredientName"
        data-hygraph-component-chain='${chain}'
      >${ingred.ingredientName}</span>
    </div>
  `;
}).join('');
```

  </TabsItem>
  <TabsItem label="Tips within recipe steps">

```js

// Type: Nested component
// Structure: Recipe → recipeSteps[] → tips[] → tip fields
// Used for: icon, title, content fields
// Path depth: 2 levels (Recipe → Recipe Step → Tip)
// Chain links: 2

// server.js

const tipsHtml = (step.tips || []).map((tip) => {
  const chain = JSON.stringify([
    { fieldApiId: 'recipeSteps', instanceId: step.id },
    { fieldApiId: 'tips', instanceId: tip.id },
  ]);

  return `
    <div>
      <h5
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="title"
        data-hygraph-component-chain='${chain}'
      >${tip.title}</h5>
      <div
        data-hygraph-entry-id="${recipe.id}"
        data-hygraph-field-api-id="content"
        data-hygraph-component-chain='${chain}'
        data-hygraph-rich-text-format="html"
      >${tip.content.html}</div>
    </div>
  `;
}).join('');
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for nested components. Extend your basic component query:

```graphql
recipeSteps {
  id
  stepNumber
  instruction { html }
  equipment {
    id        # instanceId for nested equipment
    name
    required
  }
  tips {
    id        # instanceId for nested tips
    title
    content { html }
  }
}
```

#### Modular components

Modular components can be one of several types. Branch on `__typename` and build the chain per type.

The examples below display aliased GraphQL fields such as `section.tipTitle` and `section.tipContent`. Those come from query aliases (`tipTitle: title`, `tipContent: content`). `data-hygraph-field-api-id` must still use the schema API IDs (`title`, `content`).

<Tabs>
  <TabsItem label="Featured Content">

```js

// Type: Modular component
// Structure: Recipe → featuredContent (ProTip | VideoEmbed | IngredientSpotlight)
// Used for: Single featured content section
// Path depth: 1 level
// Chain link: 1

// server.js

function renderFeaturedContent(recipe) {
  const section = recipe.featuredContent;
  if (!section) return '';

  const chain = JSON.stringify([{ fieldApiId: 'featuredContent', instanceId: section.id }]);

  switch (section.__typename) {
    case 'ProTip':
      return `
        <div>
          <div data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="icon" data-hygraph-component-chain='${chain}'>
            ${section.icon || '⭐'}
          </div>
          <h3 data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="title" data-hygraph-component-chain='${chain}'>
            ${section.tipTitle}
          </h3>
          <div
            data-hygraph-entry-id="${recipe.id}"
            data-hygraph-field-api-id="content"
            data-hygraph-component-chain='${chain}'
            data-hygraph-rich-text-format="html"
          >${section.tipContent.html}</div>
        </div>
      `;

    case 'VideoEmbed':
      return `
        <div>
          <h3 data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="title" data-hygraph-component-chain='${chain}'>
            ${section.videoTitle}
          </h3>
          <div data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="videoUrl" data-hygraph-component-chain='${chain}'>
            <!-- Video embed logic -->
          </div>
        </div>
      `;

    case 'IngredientSpotlight':
      return `
        <div>
          <div data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="image" data-hygraph-component-chain='${chain}'>
            ${section.ingredientImage ? `<img src="${section.ingredientImage.url}" alt="${section.ingredient?.name || 'Ingredient'}" width="120" height="120" />` : ''}
          </div>
          <h3 data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="ingredient" data-hygraph-component-chain='${chain}'>
            Star Ingredient: ${section.ingredient?.name || 'Unknown'}
          </h3>
        </div>
      `;

    default:
      return '';
  }
}
```

  </TabsItem>
  <TabsItem label="Additional Sections">

```js

// Type: Modular component
// Structure: Recipe → additionalSections[] (ProTip | VideoEmbed | IngredientSpotlight)[]
// Used for: Multiple additional content sections
// Path depth: 1 level
// Chain link: 1

// server.js

const additionalSectionsHtml = (recipe.additionalSections || []).map((section) => {
  const chain = JSON.stringify([{ fieldApiId: 'additionalSections', instanceId: section.id }]);

  switch (section.__typename) {
    case 'ProTip':
      return `
        <div>
          <div data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="icon" data-hygraph-component-chain='${chain}'>
            ${section.icon || '💡'}
          </div>
          <h3 data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="title" data-hygraph-component-chain='${chain}'>
            ${section.tipTitle}
          </h3>
          <div
            data-hygraph-entry-id="${recipe.id}"
            data-hygraph-field-api-id="content"
            data-hygraph-component-chain='${chain}'
            data-hygraph-rich-text-format="html"
          >${section.tipContent.html}</div>
        </div>
      `;

    case 'VideoEmbed':
      return `
        <div>
          <h3 data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="title" data-hygraph-component-chain='${chain}'>
            ${section.videoTitle}
          </h3>
        </div>
      `;

    case 'IngredientSpotlight':
      return `
        <div>
          <div data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="image" data-hygraph-component-chain='${chain}'>
            ${section.ingredientImage ? `<img src="${section.ingredientImage.url}" alt="${section.ingredient?.name || 'Ingredient'}" width="80" height="80" />` : ''}
          </div>
          <h3 data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="ingredient" data-hygraph-component-chain='${chain}'>
            Featured: ${section.ingredient?.name || 'Unknown'}
          </h3>
        </div>
      `;

    default:
      return '';
  }
}).join('');
```

  </TabsItem>
</Tabs>

### Full example

```js

// server.js

app.get('/recipes/:id', async (req, res) => {
  const { id } = req.params;
  const data = await graphqlRequest(GET_RECIPE_BY_ID_QUERY, { id });
  const recipe = data.recipe;

  if (!recipe) {
    return res.status(404).send('Recipe not found');
  }

  // Basic fields
  const titleHtml = `<h1 data-hygraph-field-api-id="title" data-hygraph-entry-id="${recipe.id}">${recipe.title}</h1>`;

  // Basic components: Ingredients
  const ingredientsHtml = recipe.ingredients.map((ingredient) => {
    const chain = JSON.stringify([{ fieldApiId: 'ingredients', instanceId: ingredient.id }]);
    return `
      <div>
        <span>${ingredient.ingredient?.name ?? ''}</span>
        <span data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="quantity" data-hygraph-component-chain='${chain}'>${ingredient.quantity}</span>
        <span data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="unit" data-hygraph-component-chain='${chain}'>${ingredient.unit}</span>
      </div>
    `;
  }).join('');

  // Basic components + nested components: Recipe Steps with Equipment
  const stepsHtml = recipe.recipeSteps.map((step) => {
    const stepChain = JSON.stringify([{ fieldApiId: 'recipeSteps', instanceId: step.id }]);

    const equipmentHtml = (step.equipment || []).map((equip) => {
      const equipChain = JSON.stringify([
        { fieldApiId: 'recipeSteps', instanceId: step.id },
        { fieldApiId: 'equipment', instanceId: equip.id },
      ]);
      return `<span data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="name" data-hygraph-component-chain='${equipChain}'>${equip.name}</span>`;
    }).join('');

    return `
      <div>
        <span data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="stepNumber" data-hygraph-component-chain='${stepChain}'>${step.stepNumber}</span>
        <div data-hygraph-entry-id="${recipe.id}" data-hygraph-field-api-id="instruction" data-hygraph-component-chain='${stepChain}' data-hygraph-rich-text-format="html">${step.instruction.html}</div>
        ${equipmentHtml}
      </div>
    `;
  }).join('');

  // Modular component: Featured Content
  const featuredContentHtml = renderFeaturedContent(recipe);

  const html = `
    <!DOCTYPE html>
    <html lang="en">
      <head><title>${recipe.title}</title></head>
      <body>
        <main>
          ${titleHtml}
          ${ingredientsHtml}
          ${stepsHtml}
          ${featuredContentHtml}
        </main>
        <script src="/js/preview-sdk.js"></script>
        <script>
          document.addEventListener('DOMContentLoaded', () => {
            if (window.HygraphPreviewSDK && window.HygraphPreviewSDK.Preview) {
              const preview = new window.HygraphPreviewSDK.Preview({
                endpoint: '${CONFIG.HYGRAPH_ENDPOINT}',
                studioUrl: '${CONFIG.HYGRAPH_STUDIO_URL}',
                debug: true,
              });
              preview.subscribe('save', { callback: () => window.location.reload() });
              window.addEventListener('beforeunload', () => preview.destroy());
            }
          });
        </script>
      </body>
    </html>
  `;

  res.send(html);
});
```

## Verify the setup

1. Open an entry in Studio for the model you configured.
2. In the right sidebar, click **Open live preview**. The preview should load alongside the entry form.
3. Hover over an element you tagged with `data-hygraph-*` attributes. An **Edit** button should appear.
4. Click **Edit**. Studio should scroll to and focus the corresponding field in the entry form.
5. Edit the field value and click **Save & Preview**. The preview should refresh and show the updated content.

If you are working with variants, no additional setup is required. Clicking a tagged element while a variant is open focuses the field directly in the variant overlay.

If the **Edit** button does not appear at step 3, set `debug: true` on the `Preview` instance and check the browser console for missing attribute warnings. Also confirm `js/preview-sdk.js` loaded successfully in the Network tab. For component fields, confirm your GraphQL query includes the `id` field on each component and that the `instanceId` values in your chain match what the query returns. For more information, see [Troubleshooting](/docs/developer-guides/schema/click-to-edit#troubleshooting).

## Related docs

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): General setup steps, attribute reference, Studio widget configuration, and troubleshooting.
- [Click to Edit - Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api): React hooks, Preview methods, DOM events, and helpers for dynamic content.
- [Live preview setup](/docs/developer-guides/schema/live-preview): Configure the Studio preview iframe before deploying Click to Edit to editors.


---
# Click to Edit - Vue / Nuxt

Source: https://hygraph.com/docs/developer-guides/schema/click-to-edit-vue-nuxt

This page walks through implementing Click to Edit in a Vue or Nuxt project using the <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Hygraph Preview SDK</Link>. By the end, editors can click any instrumented element in the preview to jump directly to that field in Studio.

For the general setup overview and configuration reference, see [Click to Edit setup](/docs/developer-guides/schema/click-to-edit). Examples for other supported frameworks are available at:
- [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router)
- [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router)
- [Remix](/docs/developer-guides/schema/click-to-edit-remix)
- [Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js)
- [Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api)

<Alert theme="info">
If you are instrumenting a frontend you did not build from scratch, start with the `PreviewWrapper` component and a single simple field. Confirm the Edit button appears and the save refresh works before adding component attributes. Components require additional data from your GraphQL queries.
</Alert>

## Steps

1. [Install the Preview SDK](#install-the-preview-sdk).
2. Set up the PreviewWrapper for your framework:
   - [Vue](#vue)
   - [Nuxt](#nuxt)
3. [Add data attributes to your content elements](#add-data-attributes-to-content-elements).
4. [Set up the Preview widget in Studio](/docs/developer-guides/schema/click-to-edit#set-up-the-preview-widget-in-studio).
5. [Verify the setup](#verify-the-setup).

## Install the Preview SDK

To install the Preview SDK, run the following command:

```bash
npm install @hygraph/preview-sdk
```

## Vue

For a client-side Vue 3 app with Vue Router. The PreviewWrapper instantiates the `Preview` class from `@hygraph/preview-sdk/core` inside `onMounted`, and tears it down in `onUnmounted`.

<Alert theme="info">
There is no framework-specific React-style component for Vue or Nuxt. The wrapper uses the `Preview` class from `@hygraph/preview-sdk/core` directly, through Vue's Composition API.
</Alert>

Running Nuxt instead of plain Vue? Use the [Nuxt](#nuxt) section below.

### Step 1: Create PreviewWrapper.vue

Create `src/components/PreviewWrapper.vue`:

```vue
<template>
  <div>
    <slot />
  </div>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { useRouter } from 'vue-router'
import type { Preview as PreviewInstance } from '@hygraph/preview-sdk/core'

const router = useRouter()
let preview: PreviewInstance | null = null

onMounted(async () => {
  if (!import.meta.env.VITE_HYGRAPH_ENDPOINT) return

  try {
    const { Preview } = await import('@hygraph/preview-sdk/core')

    preview = new Preview({
      endpoint: import.meta.env.VITE_HYGRAPH_ENDPOINT,
      studioUrl: import.meta.env.VITE_HYGRAPH_STUDIO_URL,
      debug: true,  // Optional: Enable console logging
      mode: 'iframe',  // Optional: 'iframe' | 'standalone' | 'auto'
      overlay: {  // Optional: Customize overlay styling
        style: {
          borderColor: '#3b82f6',
          borderWidth: '2px',
        },
        button: {
          backgroundColor: '#3b82f6',
          color: 'white',
        },
      },
      sync: {
        fieldFocus: true,  // Optional: Enable field focus sync from Studio
        fieldUpdate: false,  // Optional: Apply live field updates to Preview
      },
    })

    // Refresh the page on save. The core class has no `onSave` config
    // option; subscribe to the save event instead.
    preview.subscribe('save', {
      callback: () => {
        console.log('Content saved, refreshing...')
        router.go(0)
      },
    })
  } catch (error) {
    console.warn('Could not load Hygraph Preview:', error)
  }
})

onUnmounted(() => {
  if (preview) {
    preview.destroy()
    preview = null
  }
})
</script>
```

### Step 2: Register PreviewWrapper in App.vue

Wrap `<router-view />` with `PreviewWrapper` at the root of your app. If the wrapper is absent, the SDK cannot register page content and Click to Edit will not work.

```vue
<!-- src/App.vue -->
<template>
  <PreviewWrapper>
    <router-view />
  </PreviewWrapper>
</template>

<script setup lang="ts">
import PreviewWrapper from './components/PreviewWrapper.vue'
</script>
```

### Step 3: Set environment variables

Add the following to `.env.local` in your project's root directory. If you already have these from live preview setup, skip this step. Vite exposes client-side variables through the `VITE_` prefix.

```bash
# .env.local
VITE_HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
VITE_HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token  # Optional: Required if your project enforces authentication
```

**Content API endpoint**: Find this under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our documentation on the [Content API](/docs/developer-guides/project/api-access#content-api).

**Hygraph Studio base URL**: Copy from your browser's address bar in Studio. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.

**Permanent Auth Token**: Create under **Project Settings > Access > Permanent Auth Tokens**. Set the default content stage to **DRAFT**. Only required if your project enforces authentication on Content API requests. For more information, see our dedicated documentation on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).

**Configuration properties**

| Property              | Required / Optional | Description |
|-----------------------|----------------------|-------------|
| `endpoint`            | **Required**         | Hygraph Content API endpoint. To learn how to retrieve the Content API endpoint, see [our docs](/docs/developer-guides/project/api-access#content-api). |
| `studioUrl`           | Optional (recommended) | Studio base URL. Defaults to `https://app.hygraph.com`. Set this if your Studio runs on a regional or custom domain. |
| `debug`               | Optional             | Enables verbose console logs to diagnose attribute issues. |
| `mode`                | Optional             | Forces a specific mode. Options: `'iframe'` \| `'standalone'` \| `'auto'`. Auto-detection works for most cases. |
| `overlay`             | Optional             | Customize overlay border and button appearance. |
| `sync.fieldFocus`     | Optional             | Synchronizes field focus between Studio and the preview when an editor selects a field. |
| `sync.fieldUpdate`    | Optional             | Updates the preview immediately when field updates happen in Studio. Defaults to `false`. |
| `allowedOrigins`      | Optional             | Extends the list of domains that can host your preview iframe. Example: For shared preview environments (QA, staging), add the base URL here. |

The core `Preview` class has no `onSave` constructor option. Use `preview.subscribe('save', { callback })` to react to saves, and `preview.destroy()` to clean up the instance when the wrapper unmounts.

For a complete Vue example, see the <Link href="https://github.com/hygraph/preview-sdk/tree/main/examples/vue-example" target="_blank">Vue Preview SDK example</Link>.

When the wrapper and environment variables are in place, continue with [Add data attributes to content elements](#add-data-attributes-to-content-elements).

## Nuxt

Nuxt uses the same `Preview` class from `@hygraph/preview-sdk/core`. The differences from plain Vue are how you expose environment variables (`NUXT_PUBLIC_*` / `useRuntimeConfig()`), where you register the wrapper (`app.vue`), and how you refresh data after a save (`refreshNuxtData()`).

The `data-hygraph-*` attributes and component-chain helpers are the same as for Vue.

### Step 1: Create PreviewWrapper.vue

Create `components/PreviewWrapper.vue`. Initialize the SDK only on the client inside `onMounted`, and read public runtime config instead of `import.meta.env.VITE_*`.

```vue
<template>
  <div>
    <slot />
  </div>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import type { Preview as PreviewInstance } from '@hygraph/preview-sdk/core'

const config = useRuntimeConfig()
let preview: PreviewInstance | null = null

onMounted(async () => {
  const endpoint = config.public.hygraphEndpoint
  if (!endpoint) return

  try {
    const { Preview } = await import('@hygraph/preview-sdk/core')

    preview = new Preview({
      endpoint,
      studioUrl: config.public.hygraphStudioUrl,
      debug: true,  // Optional: Enable console logging
      mode: 'iframe',  // Optional: 'iframe' | 'standalone' | 'auto'
      overlay: {  // Optional: Customize overlay styling
        style: {
          borderColor: '#3b82f6',
          borderWidth: '2px',
        },
        button: {
          backgroundColor: '#3b82f6',
          color: 'white',
        },
      },
      sync: {
        fieldFocus: true,  // Optional: Enable field focus sync from Studio
        fieldUpdate: false,  // Optional: Apply live field updates to Preview
      },
    })

    // Re-fetch Nuxt data on save instead of a full page reload
    preview.subscribe('save', {
      callback: () => {
        console.log('Content saved, refreshing...')
        refreshNuxtData()
      },
    })
  } catch (error) {
    console.warn('Could not load Hygraph Preview:', error)
  }
})

onUnmounted(() => {
  if (preview) {
    preview.destroy()
    preview = null
  }
})
</script>
```

### Step 2: Register PreviewWrapper in app.vue

Wrap `<NuxtPage />` with `PreviewWrapper` in `app.vue`. If the wrapper is absent, the SDK cannot register page content and Click to Edit will not work.

```vue
<!-- app.vue -->
<template>
  <PreviewWrapper>
    <NuxtPage />
  </PreviewWrapper>
</template>
```

Nuxt auto-imports components from `components/`, so you usually do not need a manual import.

### Step 3: Configure runtime config and environment variables

Expose only the values the browser needs through `runtimeConfig.public`. Keep Permanent Auth Tokens server-side if you use them for GraphQL queries.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only (optional): used by your GraphQL loaders, not by the Preview SDK
    hygraphToken: process.env.HYGRAPH_TOKEN,
    public: {
      hygraphEndpoint: process.env.NUXT_PUBLIC_HYGRAPH_ENDPOINT,
      hygraphStudioUrl: process.env.NUXT_PUBLIC_HYGRAPH_STUDIO_URL,
    },
  },
})
```

Add the following to `.env` in your project's root directory. If you already have these from live preview setup, map the public endpoint and Studio URL into `NUXT_PUBLIC_*` as shown.

```bash
# .env
NUXT_PUBLIC_HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
NUXT_PUBLIC_HYGRAPH_STUDIO_URL=https://your-region.hygraph.com
HYGRAPH_TOKEN=your-permanent-auth-token  # Optional: server-only; required if your project enforces authentication
```

**Content API endpoint**: Find this under **Project Settings > Access > Endpoints > High Performance Content API**. For more information, see our documentation on the [Content API](/docs/developer-guides/project/api-access#content-api).

**Hygraph Studio base URL**: Copy from your browser's address bar in Studio. Example: `https://studio-eu-central-1-shared-euc1-02.hygraph.com`.

**Permanent Auth Token**: Create under **Project Settings > Access > Permanent Auth Tokens**. Set the default content stage to **DRAFT**. Only required if your project enforces authentication on Content API requests. Keep this value out of `runtimeConfig.public`. For more information, see our dedicated documentation on [Permanent Auth Tokens](/docs/developer-guides/project/api-access#permanent-auth-tokens).

When the wrapper and environment variables are in place, continue with [Add data attributes to content elements](#add-data-attributes-to-content-elements).

## Add data attributes to content elements

Data attributes (`data-hygraph-*`) connect your rendered elements to specific Hygraph fields. The SDK reads these attributes and attaches Edit overlays automatically. The same attributes work for variants; no additional instrumentation is required. For the full attribute reference, see [Add data attributes to content elements](/docs/developer-guides/schema/click-to-edit#add-data-attributes-to-content-elements).

The examples below use a recipe model. To bootstrap the same Hygraph project used here, follow the <Link href="https://github.com/hygraph/preview-sdk/blob/main/examples/project-setup/README.md" target="_blank">project setup instructions</Link>.

In Vue, read the route id with `useRoute()` from `vue-router` and fetch the entry inside `onMounted`, re-fetching with a `watch` on the route param. In Nuxt, use the same `useRoute()` composable with file-based routes (for example `pages/recipes/[id].vue`) and prefer `useAsyncData` or `useFetch` for the query. Static attribute values can be written directly; dynamic values need Vue's `:` binding shorthand.

```vue
<script setup lang="ts">
import { ref, onMounted, watch } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()
const recipe = ref(null)

const fetchRecipe = async (id: string) => {
  recipe.value = await getRecipe(id)
}

onMounted(() => {
  const id = Array.isArray(route.params.id) ? route.params.id[0] : route.params.id
  if (id) fetchRecipe(id)
})

watch(
  () => route.params.id,
  (newId) => {
    const id = Array.isArray(newId) ? newId[0] : newId
    if (id) fetchRecipe(id)
  }
)
</script>
```

### Simple fields

Add `data-hygraph-entry-id` and `data-hygraph-field-api-id` to any element rendering a Hygraph field value.

```vue

<!-- src/views/Recipe.vue -->

<template>
  <main v-if="recipe">
    <!-- Title -->
    <h1
      data-hygraph-field-api-id="title"
      :data-hygraph-entry-id="recipe.id"
    >
      {{ recipe.title }}
    </h1>

    <!-- Description -->
    <div
      data-hygraph-field-api-id="description"
      :data-hygraph-entry-id="recipe.id"
      data-hygraph-rich-text-format="html"
      v-html="recipe.description.html"
    ></div>

    <!-- Recipe Meta -->
    <div data-hygraph-field-api-id="prepTime" :data-hygraph-entry-id="recipe.id">
      {{ recipe.prepTime }}
    </div>

    <div data-hygraph-field-api-id="cookTime" :data-hygraph-entry-id="recipe.id">
      {{ recipe.cookTime }}
    </div>

    <div data-hygraph-field-api-id="servings" :data-hygraph-entry-id="recipe.id">
      {{ recipe.servings }}
    </div>

    <div data-hygraph-field-api-id="difficulty" :data-hygraph-entry-id="recipe.id">
      {{ recipe.difficulty }}
    </div>

    <!-- Hero Image -->
    <div
      data-hygraph-field-api-id="heroImage"
      :data-hygraph-entry-id="recipe.id"
    >
      <img v-if="recipe.heroImage?.url" :src="recipe.heroImage.url" :alt="recipe.title" />
    </div>
  </main>
</template>
```

### Component fields

Components require the `data-hygraph-component-chain` attribute so Studio can navigate to the correct nested field instance. Use the helper functions from `@hygraph/preview-sdk/core`, imported in `<script setup>` and called directly in the template with `v-bind`:

```ts
import {
  createComponentChainLink,
  createPreviewAttributes,
  withFieldPath,
} from '@hygraph/preview-sdk/core'
```

The `instanceId` in each chain link is the `id` field of the component instance returned in your GraphQL query. It is not the component type's API ID. Query for `id` on every component you want to instrument. See the GraphQL example in [Basic components](#basic-components) below.

#### Basic components

These are direct children of the Recipe model, and are not nested inside other components. Each one uses a single-link chain.

<Tabs>
  <TabsItem label="Ingredients">

```vue

<!-- Type: Basic component -->
<!-- Structure: Recipe → ingredients[] → ingredient fields -->
<!-- Used for: quantity, unit fields -->
<!-- Path depth: 1 level (Recipe → Ingredient) -->
<!-- Chain link: 1 -->

<!-- src/views/Recipe.vue -->

<template>
  <div v-for="(ingredient, index) in recipe.ingredients" :key="ingredient.id">
    <span>{{ ingredient.ingredient?.name }}</span>
    <span
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'quantity',
          componentChain: [createComponentChainLink('ingredients', ingredient.id)],
        }),
        `ingredients.${index}.quantity`
      )"
    >
      {{ ingredient.quantity }}
    </span>
    <span
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'unit',
          componentChain: [createComponentChainLink('ingredients', ingredient.id)],
        }),
        `ingredients.${index}.unit`
      )"
    >
      {{ ingredient.unit }}
    </span>
  </div>
</template>
```

  </TabsItem>
  <TabsItem label="Recipe steps">

```vue

<!-- Type: Basic component -->
<!-- Structure: Recipe → recipeSteps[] → step fields -->
<!-- Used for: stepNumber, title, instruction, estimatedTime -->
<!-- Path depth: 1 level (Recipe → Recipe Step) -->
<!-- Chain link: 1 -->

<!-- src/views/Recipe.vue -->

<template>
  <div v-for="(step, index) in recipe.recipeSteps" :key="step.id">
    <span
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'stepNumber',
          componentChain: [createComponentChainLink('recipeSteps', step.id)],
        }),
        `recipeSteps.${index}.stepNumber`
      )"
    >
      {{ step.stepNumber }}
    </span>
    <h3
      v-if="step.title"
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: [createComponentChainLink('recipeSteps', step.id)],
        }),
        `recipeSteps.${index}.title`
      )"
    >
      {{ step.title }}
    </h3>
    <div
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'instruction',
          componentChain: [createComponentChainLink('recipeSteps', step.id)],
        }),
        `recipeSteps.${index}.instruction`
      )"
      data-hygraph-rich-text-format="html"
      v-html="step.instruction.html"
    ></div>
  </div>
</template>
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for basic components:

```graphql
query GetRecipe($id: ID!) {
  recipe(where: { id: $id }, stage: DRAFT) {
    id
    title
    ingredients {
      id        # instanceId for the ingredient component
      quantity
      unit
    }
    recipeSteps {
      id        # instanceId for the step component
      stepNumber
      instruction { html }
    }
  }
}
```

#### Nested components

Nested components require a multi-link chain, ordered from the outermost to the innermost component.

<Tabs>
  <TabsItem label="Equipment within recipe steps">

```vue

<!-- Type: Nested component -->
<!-- Structure: Recipe → recipeSteps[] → equipment[] → equipment fields -->
<!-- Used for: name, required, alternatives, notes fields -->
<!-- Path depth: 2 levels (Recipe → Recipe Step → Equipment) -->
<!-- Chain links: 2 -->

<!-- src/views/Recipe.vue -->

<template>
  <div
    v-for="(equip, equipIndex) in step.equipment"
    :key="equip.id"
  >
    <span
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'name',
          componentChain: [
            createComponentChainLink('recipeSteps', step.id),
            createComponentChainLink('equipment', equip.id),
          ],
        }),
        `recipeSteps.${index}.equipment.${equipIndex}.name`
      )"
    >
      {{ equip.name }}
    </span>
    <span
      v-if="equip.required"
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'required',
          componentChain: [
            createComponentChainLink('recipeSteps', step.id),
            createComponentChainLink('equipment', equip.id),
          ],
        }),
        `recipeSteps.${index}.equipment.${equipIndex}.required`
      )"
    >
      Required
    </span>
  </div>
</template>
```

  </TabsItem>
  <TabsItem label="Ingredients used within recipe steps">

```vue

<!-- Type: Nested component -->
<!-- Structure: Recipe → recipeSteps[] → ingredientsUsed[] → ingredient fields -->
<!-- Used for: ingredientName, preparation, timing, notes fields -->
<!-- Path depth: 2 levels (Recipe → Recipe Step → Ingredient Reference) -->
<!-- Chain links: 2 -->

<!-- src/views/Recipe.vue -->

<template>
  <div
    v-for="(ingred, ingredIndex) in step.ingredientsUsed"
    :key="ingred.id"
  >
    <span
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'ingredientName',
          componentChain: [
            createComponentChainLink('recipeSteps', step.id),
            createComponentChainLink('ingredientsUsed', ingred.id),
          ],
        }),
        `recipeSteps.${index}.ingredientsUsed.${ingredIndex}.ingredientName`
      )"
    >
      {{ ingred.ingredientName }}
    </span>
  </div>
</template>
```

  </TabsItem>
  <TabsItem label="Tips within recipe steps">

```vue

<!-- Type: Nested component -->
<!-- Structure: Recipe → recipeSteps[] → tips[] → tip fields -->
<!-- Used for: icon, title, content fields -->
<!-- Path depth: 2 levels (Recipe → Recipe Step → Tip) -->
<!-- Chain links: 2 -->

<!-- src/views/Recipe.vue -->

<template>
  <div v-for="(tip, tipIndex) in step.tips" :key="tip.id">
    <h5
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'title',
          componentChain: [
            createComponentChainLink('recipeSteps', step.id),
            createComponentChainLink('tips', tip.id),
          ],
        }),
        `recipeSteps.${index}.tips.${tipIndex}.title`
      )"
    >
      {{ tip.title }}
    </h5>
    <div
      v-bind="withFieldPath(
        createPreviewAttributes({
          entryId: recipe.id,
          fieldApiId: 'content',
          componentChain: [
            createComponentChainLink('recipeSteps', step.id),
            createComponentChainLink('tips', tip.id),
          ],
        }),
        `recipeSteps.${index}.tips.${tipIndex}.content`
      )"
      data-hygraph-rich-text-format="html"
      v-html="tip.content.html"
    ></div>
  </div>
</template>
```

  </TabsItem>
</Tabs>

GraphQL query to retrieve `instanceId` values for nested components. Extend your basic component query:

```graphql
recipeSteps {
  id
  stepNumber
  instruction { html }
  equipment {
    id        # instanceId for nested equipment
    name
    required
  }
  tips {
    id        # instanceId for nested tips
    title
    content { html }
  }
}
```

#### Modular components

Modular components can be one of several types. Use `__typename` to branch and build the chain per type.

The examples below display aliased GraphQL fields such as `recipe.featuredContent.tipTitle` and `section.tipContent`. Those come from query aliases (`tipTitle: title`, `tipContent: content`). `fieldApiId` must still use the schema API IDs (`title`, `content`).

<Tabs>
  <TabsItem label="Featured Content">

```vue

<!-- Type: Modular component -->
<!-- Structure: Recipe → featuredContent (ProTip | VideoEmbed | IngredientSpotlight) -->
<!-- Used for: Single featured content section -->
<!-- Path depth: 1 level -->
<!-- Chain link: 1 -->

<!-- src/views/Recipe.vue -->

<template>
  <div v-if="recipe.featuredContent">
    <template v-if="recipe.featuredContent.__typename === 'ProTip'">
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'icon',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.icon'
        )"
      >
        {{ recipe.featuredContent.icon || '⭐' }}
      </div>
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.title'
        )"
      >
        {{ recipe.featuredContent.tipTitle }}
      </h3>
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'content',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.content'
        )"
        data-hygraph-rich-text-format="html"
        v-html="recipe.featuredContent.tipContent.html"
      ></div>
    </template>

    <template v-else-if="recipe.featuredContent.__typename === 'VideoEmbed'">
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.title'
        )"
      >
        {{ recipe.featuredContent.videoTitle }}
      </h3>
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'videoUrl',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.videoUrl'
        )"
      >
        <!-- Video embed logic -->
      </div>
    </template>

    <template v-else-if="recipe.featuredContent.__typename === 'IngredientSpotlight'">
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'image',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.image'
        )"
      >
        <img
          v-if="recipe.featuredContent.ingredientImage"
          :src="recipe.featuredContent.ingredientImage.url"
          :alt="recipe.featuredContent.ingredient?.name || 'Ingredient'"
          width="120"
          height="120"
        />
      </div>
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'ingredient',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.ingredient'
        )"
      >
        Star Ingredient: {{ recipe.featuredContent.ingredient?.name || 'Unknown' }}
      </h3>
    </template>
  </div>
</template>
```

  </TabsItem>
  <TabsItem label="Additional Sections">

```vue

<!-- Type: Modular component -->
<!-- Structure: Recipe → additionalSections[] (ProTip | VideoEmbed | IngredientSpotlight)[] -->
<!-- Used for: Multiple additional content sections -->
<!-- Path depth: 1 level -->
<!-- Chain link: 1 -->

<!-- src/views/Recipe.vue -->

<template>
  <div v-for="(section, index) in recipe.additionalSections" :key="section.id">
    <template v-if="section.__typename === 'ProTip'">
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'icon',
            componentChain: [createComponentChainLink('additionalSections', section.id)],
          }),
          `additionalSections.${index}.icon`
        )"
      >
        {{ section.icon || '💡' }}
      </div>
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: [createComponentChainLink('additionalSections', section.id)],
          }),
          `additionalSections.${index}.title`
        )"
      >
        {{ section.tipTitle }}
      </h3>
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'content',
            componentChain: [createComponentChainLink('additionalSections', section.id)],
          }),
          `additionalSections.${index}.content`
        )"
        data-hygraph-rich-text-format="html"
        v-html="section.tipContent.html"
      ></div>
    </template>

    <template v-else-if="section.__typename === 'VideoEmbed'">
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: [createComponentChainLink('additionalSections', section.id)],
          }),
          `additionalSections.${index}.title`
        )"
      >
        {{ section.videoTitle }}
      </h3>
    </template>

    <template v-else-if="section.__typename === 'IngredientSpotlight'">
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'image',
            componentChain: [createComponentChainLink('additionalSections', section.id)],
          }),
          `additionalSections.${index}.image`
        )"
      >
        <img
          v-if="section.ingredientImage"
          :src="section.ingredientImage.url"
          :alt="section.ingredient?.name || 'Ingredient'"
          width="80"
          height="80"
        />
      </div>
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'ingredient',
            componentChain: [createComponentChainLink('additionalSections', section.id)],
          }),
          `additionalSections.${index}.ingredient`
        )"
      >
        Featured: {{ section.ingredient?.name || 'Unknown' }}
      </h3>
    </template>
  </div>
</template>
```

  </TabsItem>
</Tabs>

### Full example

```vue

<!-- src/views/Recipe.vue -->

<template>
  <main v-if="recipe">
    <!-- Basic fields -->

    <h1 data-hygraph-field-api-id="title" :data-hygraph-entry-id="recipe.id">
      {{ recipe.title }}
    </h1>

    <div
      data-hygraph-field-api-id="description"
      :data-hygraph-entry-id="recipe.id"
      data-hygraph-rich-text-format="html"
      v-html="recipe.description.html"
    ></div>

    <div data-hygraph-field-api-id="prepTime" :data-hygraph-entry-id="recipe.id">
      {{ recipe.prepTime }}min
    </div>

    <div data-hygraph-field-api-id="categories" :data-hygraph-entry-id="recipe.id">
      <span v-for="category in recipe.categories" :key="category.id">
        {{ category.name }}
      </span>
    </div>

    <!-- Basic components: Ingredients -->
    <div v-for="(ingredient, index) in recipe.ingredients" :key="ingredient.id">
      <span>{{ ingredient.ingredient?.name }}</span>
      <span
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'quantity',
            componentChain: [createComponentChainLink('ingredients', ingredient.id)],
          }),
          `ingredients.${index}.quantity`
        )"
      >
        {{ ingredient.quantity }}
      </span>
      <span
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'unit',
            componentChain: [createComponentChainLink('ingredients', ingredient.id)],
          }),
          `ingredients.${index}.unit`
        )"
      >
        {{ ingredient.unit }}
      </span>
    </div>

    <!-- Basic components: Recipe Steps -->
    <div v-for="(step, index) in recipe.recipeSteps" :key="step.id">
      <span
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'stepNumber',
            componentChain: [createComponentChainLink('recipeSteps', step.id)],
          }),
          `recipeSteps.${index}.stepNumber`
        )"
      >
        {{ step.stepNumber }}
      </span>
      <h3
        v-if="step.title"
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: [createComponentChainLink('recipeSteps', step.id)],
          }),
          `recipeSteps.${index}.title`
        )"
      >
        {{ step.title }}
      </h3>
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'instruction',
            componentChain: [createComponentChainLink('recipeSteps', step.id)],
          }),
          `recipeSteps.${index}.instruction`
        )"
        data-hygraph-rich-text-format="html"
        v-html="step.instruction.html"
      ></div>

      <!-- Nested components: Equipment within this step -->
      <div v-for="(equip, equipIndex) in step.equipment" :key="equip.id">
        <span
          v-bind="withFieldPath(
            createPreviewAttributes({
              entryId: recipe.id,
              fieldApiId: 'name',
              componentChain: [
                createComponentChainLink('recipeSteps', step.id),
                createComponentChainLink('equipment', equip.id),
              ],
            }),
            `recipeSteps.${index}.equipment.${equipIndex}.name`
          )"
        >
          {{ equip.name }}
        </span>
        <span v-if="equip.required">Required</span>
      </div>
    </div>

    <!-- Modular components: Featured Content -->
    <div v-if="recipe.featuredContent && recipe.featuredContent.__typename === 'ProTip'">
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'icon',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.icon'
        )"
      >
        {{ recipe.featuredContent.icon }}
      </div>
      <h3
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'title',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.title'
        )"
      >
        {{ recipe.featuredContent.tipTitle }}
      </h3>
      <div
        v-bind="withFieldPath(
          createPreviewAttributes({
            entryId: recipe.id,
            fieldApiId: 'content',
            componentChain: [createComponentChainLink('featuredContent', recipe.featuredContent.id)],
          }),
          'featuredContent.content'
        )"
        data-hygraph-rich-text-format="html"
        v-html="recipe.featuredContent.tipContent.html"
      ></div>
    </div>
  </main>
</template>

<script setup lang="ts">
import { createComponentChainLink, createPreviewAttributes, withFieldPath } from '@hygraph/preview-sdk/core'
// recipe is fetched via useRoute() + onMounted/watch, see "Add data attributes to content elements" above
</script>
```

## Verify the setup

1. Open an entry in Studio for the model you configured.
2. In the right sidebar, click **Open live preview**. The preview should load alongside the entry form.
3. Hover over an element you tagged with `data-hygraph-*` attributes. An **Edit** button should appear.
4. Click **Edit**. Studio should scroll to and focus the corresponding field in the entry form.
5. Edit the field value and click **Save & Preview**. The preview should refresh and show the updated content.

If you are working with variants, no additional setup is required. Clicking a tagged element while a variant is open focuses the field directly in the variant overlay.

If the **Edit** button does not appear at step 3, set `debug: true` on the `Preview` instance and check the browser console for missing attribute warnings. For component fields, confirm your GraphQL query includes the `id` field on each component and that the `instanceId` values in your chain match what the query returns. For more information, see [Troubleshooting](/docs/developer-guides/schema/click-to-edit#troubleshooting).

## Related docs

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): General setup steps, attribute reference, Studio widget configuration, and troubleshooting.
- [Click to Edit - Advanced API](/docs/developer-guides/schema/click-to-edit-advanced-api): React hooks, Preview methods, DOM events, and helpers for dynamic content.
- [Live preview setup](/docs/developer-guides/schema/live-preview): Configure the Studio preview iframe before deploying Click to Edit to editors.
- [Live preview - Frontend implementation](/docs/developer-guides/schema/live-preview-frontend): Serve DRAFT content for Vue, Nuxt, and other frameworks.


---
# Command menu

Source: https://hygraph.com/docs/developer-guides/schema/command-menu

Some schema management tasks require completing a series of similar repeated actions with a lot of confirmation popups.

Hygraph Studio allows keyboard navigation through the command menu, which greatly speeds up the process.

## How it works

To trigger the popup search bar, simply use `CMD+K` (or `CTRL+K` in Windows).

![Command menu](/images/docs/user-guides/command-menu.png)

You can also bring up the command menu by clicking `Search` in the top bar:

![Command menu - Search](/images/docs/user-guides/command-menu-navigate.png)

Type in the search bar to filter the list of available actions. When calling the command menu, both the global functions - navigation, global commands - and context-specific commands are available.

Navigate the list of suggested actions using the Up/Down arrows on your keyboard, or your mouse-wheel. To confirm your selection, use the Enter key or a mouse click.

## Navigation capabilities

Depending on the section of the app you're in, the command menu will prioritize which set of actions to show first.

### Top-level navigation

![Command menu - Top-level navigation](/images/docs/user-guides/command-menu-top-level.png)

The **Go-to** section offers shortcuts to:
- Schema
- Content
- Assets
- API Playground
- Apps
- Webhooks
- Project settings

### Schema

![Command menu - Schema](/images/docs/user-guides/command-menu-contextual-schema.png)

The **Schema** section offers shortcuts to:

- System and user-defined models in the Schema builder
- User-defined components in the Schema builder
- User-defined enumerations in the Schema builder

### Content table

![Command menu - Content table](/images/docs/user-guides/command-menu-contextual-content.png)

The **Content table** section offers shortcuts to:

- User-defined models in the Content editor
- User-defined custom views in the Content editor

## Add actions

You can create schema elements as well as content entries directly from the command menu.

### Add schema

![Command menu - Add schema](/images/docs/user-guides/command-menu-add-schema.png)

The **Add Schema** section offers shortcuts to create new schema elements.

You can click on the options there to add a new model, component, remote source or enumeration.

### Add content

![Command menu - Add content](/images/docs/user-guides/command-menu-add-content.png)

The **Add Content** section offers shortcuts to create new content entries for any of the models currently in your Schema.

## Project settings

![Command menu - Project settings](/images/docs/user-guides/command-menu-project-settings.png)

The **Project settings** section offers shortcuts to each part of your project settings.

## Recently viewed

![Command menu - Recently viewed](/images/docs/user-guides/command-menu-recently-viewed.png)

The **Recently viewed** section offers shortcuts to your recently viewed content entries

[Click here to learn more about the recently viewed menu.](/docs/developer-guides/schema/recently-viewed)


---
# Components

Source: https://hygraph.com/docs/developer-guides/schema/components

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. |

<Alert theme="info">

**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.

</Alert>

## 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](/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).

<Alert theme="info">

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

</Alert>

### Create a component

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xayvhu9b07vx89uwd88w" caption="Creating a component in the Schema Builder" />

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](/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.

<Alert theme="info">

The number of components you can create depends on your Hygraph plan. See <Link href="https://hygraph.com/pricing" target="_blank">pricing details</Link>.

</Alert>

### Add a component field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xa50hu7207vx78msiw7j" caption="Adding a component field to a model in the Schema Builder" />

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](/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

<VideoEmbed videoId="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

<Alert theme="info">

**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.

</Alert>

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.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkgbmf6ozk2606uomkkajmni" caption="Duplicate component instances in an entry" />

### 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.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmmj24vr8ys0w07w2uhezxj98" caption="Copy and paste component instances" />

<Alert theme="info">

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.

</Alert>

## 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.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xuufjbqk07w5t5q77gny" caption="Adding a nested component in the Schema Builder" />

1. Open a component you've [already created](/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](/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.

<Alert theme="info">

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

</Alert>

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

## Related docs

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


---
# Components or references

Source: https://hygraph.com/docs/developer-guides/schema/components-or-references

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.

## Definitions

![Components](/images/docs/user-guides/components-illustration.png)

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](/images/docs/user-guides/reference-illustration.png)

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.

## How to choose

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.

### Repeated content

**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**

- With **references**, create author entries in a dedicated `Author` model, then link them to posts. This works well when you have a known set of authors, each with their own profile.
- With **components**, add an author component instance directly to each post and fill in the fields each time. This works well when many different people can be authors and maintaining individual author profiles isn't practical.

### Simplified content creation screen

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.

### Editor experience

**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:**

- Use references when linking to something that already exists.
- Use components when creating content from scratch, unless the component would be very large, in which case a reference with an overlay may provide a better editing experience.

### Content duplication

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:

- Two-way references with many-to-many or many-to-one cardinality, where more than one model can be referenced.
- Two-way references with many-to-many cardinality, where only one model can be referenced.

Components are always duplicated with their parent entry.

For a complete breakdown, see [Duplicating content](/docs/developer-guides/content/duplicating-content).

### Conclusion

**Use components when:**

- Your project reuses the same field structure across multiple models.
- Content is created from scratch each time the structure is reused.
- You want a simplified, dynamic content creation screen for editors.
- Your project relies on content duplication.

**Use references when:**

- You want to link to content that already exists.
- Content is reused unchanged across multiple entries. For example, a shared set of related posts in a blog.
- The related content is large enough that completing it in an overlay is preferable to filling it in inline.

## Combining components and references

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.

## Example use cases

**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.

---
# Conditional fields

Source: https://hygraph.com/docs/developer-guides/schema/conditional-fields

## Overview

Conditional visibility shows Hygraph's commitment to increasing the productivity of editors and developers who are dealing with complex content.

As deeply nested content structures can sometimes challenge editors, conditional visibility allows to show selected fields only when editors truly need them.

## What you can do

You can use the conditional visibility option on the configuration of certain fields to make them visible or hidden in the content editor.

The main use case for conditional fields is to simplify the content form when a  model contains complex nested menu structures, where each item may serve as a link or as another layer of dropdowns.

<Alert theme="info" title="Example situation">

[Check out our example](/docs/developer-guides/schema/conditional-fields#nested-structures-example) on how to use conditional visibility to simplify a content form that uses nested components!

</Alert>

## Conditional visibility

You will find the `Conditional visibility` option in your field configuration, in the `Advanced` tab.

![Conditional visibility inside field details](/images/docs/user-guides/conditional-fields/field-visibility-checkbox.png)

When you select the checkbox, more options display:

![Conditional visibility options](/images/docs/user-guides/conditional-fields/field-visibility-options.png)

The dropdown will allow you to select a [Boolean](/docs/developer-guides/schema/conditional-fields#boolean-field) or an [Enumeration](/docs/developer-guides/schema/conditional-fields#enumeration-field) field from the same model, which will be used to set the condition.

Condition setting differs depending on which field type you select from the dropdown. The following sections explain how to set conditions using each type.

### Boolean field

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xamdhu8207vxq93umsjt" caption="Conditional visibility - Boolean" />

If you select a boolean field from the `Conditional visibility` dropdown you will have the option to select `is` or `is not` in the following dropdown, and then `true` or `false` in the last one.

Let's look into an example of how this works. Imagine we have a schema for a bookshop, with a model for **Author** and a model for **Product** (books). In the **Author** model, we have a boolean field called **In stock**, followed by a reference field that allows adding related books.

The reference field has conditional visibility settings that use the **In stock** boolean and are set to `In stock is true`. This means that the reference field to add books will only display in the content editor if you set the **In stock** boolean to `true`.

Here's a video showing you how we set this up:

<VideoEmbed videoId="NXiG_baCY8Y" />

Similarly, you could have a component that displays information about when a book will be in stock and use the same **In stock** boolean to set the condition to `In stock is false`. In this case, if your book is not in stock and so you set the boolean to `false`, the component will display on the content form for your editors to add information about when the product will be available.

<Alert type="warning" title="Is your conditional visibility checkbox grayed out?">

[Check out our troubleshooting section!](/docs/developer-guides/schema/conditional-fields#troubleshooting)

</Alert>

### Enumeration field

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xaohhu8a07vxun01trur" caption="Conditional visibility - Enumeration" />

If you select an enumeration field from the `Conditional visibility` dropdown you will have the option to select one of the following conditions in combination with one of the enumeration values:

| Condition                   | Description                                                                               |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| **`is` + Value**            | The field is visible if the enumeration value is selected in the content form.            |
| **`is not` + Value**        | The field is visible if the enumeration value is not selected in the content form.        |
| **`contains any` + Value**  | The field is visible if at least one of the indicated the enumeration values is selected. |
| **`contains all` + Value**  | The field is visible if all of the indicated the enumeration values are selected.         |
| **`contains none` + Value** | The field is visible if none of the indicated the enumeration values are selected.        |

<Alert theme="info" title="Pro Tip">

The conditions `contain all` and `contain any` work with enumeration fields that allow multiple values.

</Alert>

Let's look into an example of how this works. Imagine we have a schema for a bookshop, with a model for **Author** and a model for **Product** (books). In the **Author** model, we have an enumeration field called **Offers** containing 3 values (Location 1, Location 2, Location 3), followed by a reference field that allows adding related books that are on sale.

The reference field has conditional visibility settings that use the **Offers** enumeration and are set to `Offers is Location 2`. This means that the reference field to add books on sale will only display in the content editor if you use the **Offers** dropdown to select the `Location 2` value.

Here's a video showing you how we set this up:

<VideoEmbed videoId="z3_OUUHbyU8" />

<Alert type="warning" title="Is your conditional visibility checkbox grayed out?">

[Check out our troubleshooting section!](/docs/developer-guides/schema/conditional-fields#troubleshooting)

</Alert>

### Edit the base field

If you edit the base field - boolean or enumeration - by changing the selected condition on the content form, the content stored in hidden conditional fields will be deleted upon saving the content entry. This is done in order to ensure consistency of the data.

This applies when you change any of the visibility conditions from `TRUE` to `FALSE` or `null` (by clearing the boolean field in the content form).

## Nested structures example

The conditional visibility functionality is especially useful for simplifying content forms by only showing sections when the configured conditions are met.

Check out the following video to see how conditional visibility does this with nested components:

<VideoEmbed videoId="u56iU-_hV9c" />

## Troubleshooting

Is your `Conditional visibility` checkbox grayed out? This can help:

| Check                                                          | Solution                                                                                                                                                                            |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Is your field required?**                                    | Conditional visibility does not support required fields. **Deselect the `Make field required` checkbox to enable conditional visibility.**                                          |
| **Is your field hidden?**                                      | Conditional visibility does not support hidden fields. **Set the `field visibility` to `Read / Write` or `Read only` to enable conditional visibility.**                            |
| **Do you have a boolean or enumeration field in your schema?** | Conditional visibility uses boolean or enumeration fields in the model you're working on. **Add a `Boolean` or `Enumeration` field to your model to enable conditional visibility** |



---
# Content Finder

Source: https://hygraph.com/docs/developer-guides/schema/content-finder

## Overview

Content Finder lets you quickly search across all content in your environment, including text fields in models and nested components.
The Content Finder search shows a list of all content entries in your environment that match the search terms, listing the most relevant ones at the top, while searching through Single Line, Multi-Line, Markdown, and RichText fields.

## Using Content Finder

1. Click the icon next to `Search` in the top bar or open the Command Menu with `CMD+K` (or CTRL+K in Windows).
2. Type keywords in the search field and click enter.
3. Select a content entry from the results list to access it in the Content Editor.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmbeu4j1l2ng007w1a0kpzwci" caption="How to use Content Finder" />

The results list shows the top-matching content entries at the top, and you can access any of them with a click. If you need to access another content entry that has the specified search term, click `Search` or open the Command Menu to view the search results again.

<Alert theme="info" title="Pro Tip">

- Content Finder's search index refreshes when you make content or schema changes, ensuring the search results are always up-to-date.
- Content Finder supports Single-Line, Multi-Line, Markdown, and Rich Text fields.

</Alert>

Content Finder will search all supported fields, not just the title:

![Content Finder search results](/images/docs/user-guides/content-finder/content-finder-search-results.png)

It helps editors easily identify the content entry they're looking for.

<Alert theme="info" title="Did you open the wrong content entry?">

The Command Menu - where you will find the Content Finder feature - keeps your results until you start a new search, so you can open it again and continue looking through your results list.

</Alert>

## Search results & permissions

Content Finder shows results depending on the permissions the user has. For instance, if an Editor only has `READ` permissions for two models, the search results will only show those two models.

However, conditional permissions are not yet supported.

## Content Finder limitations

Content Finder has the following limitations:

- Content Finder only supports exact matches. For instance, if you look for “portrait” rather than “portraits”, only results with the word “portrait” in them will display.
- Content Finder shows a maximum of 20 results at a time. You need to click Load more to see additional results.
- Custom roles with conditional content permissions cannot search through models where [conditions](/docs/getting-started/access-and-permissions/user-roles-and-permissions#using-conditions) apply. They can only search models where they have unconditional read access. System roles (Admins, Developers, Editors, Contributors) can search across all models, as they have full read access to all entries.


---
# Import schema

Source: https://hygraph.com/docs/developer-guides/schema/import-schema

Import schema elements from a Hygraph project or template that you are a member of into your current project and environment. You can import models, components, remote sources, enumerations, and taxonomies without rebuilding them manually.

## When to use this feature

Use this feature when you want to:

- Reuse schema patterns across projects, such as shared components, enumerations, or taxonomies.
- Import specific elements instead of [cloning an entire project](/docs/developer-guides/project/clone-your-project).
- Bootstrap a new project from a template or starter.
- Keep shared domain models consistent across related projects.
- Speed up prototyping with existing building blocks.

## What this feature does not do

- It does not import elements you do not have permission to create.
- It does not replace or merge your existing schema as a whole.
- It does not import content entries.
- It does not overwrite existing schema elements. Conflicting names must be renamed on import.

For schema export/import through the Management API or SDK, see [Schema as code](/docs/api-reference/schema/schema-as-code).

## Permissions

When you import schema elements, Hygraph respects your role's [permissions](/docs/getting-started/access-and-permissions/management-api-permissions). You can only import elements you have permission to create. For example, if your role lets you create models but not enumerations, Hygraph excludes enumeration elements from the list in [Select elements](#step-2-select-elements) and you can only import models.

## Get started

In Hygraph Studio, go to **Schema > Import** to start the import wizard. 

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmsrg91x3pesz08uxcgee2azf" caption="Import schema elements" />

### Step 1: Select a project

Choose the **Source Project** to import from. The list includes:

- **Projects** you are a member of (your current project is excluded)
- **Templates & Starters** available to you

After you select a source, click **Continue**. Hygraph loads the source project's schema so you can choose elements in the next step.

### Step 2: Select elements

Hygraph only lists elements you have permission to create. See [Permissions](#permissions). You can browse schema elements from the source project, grouped by type:

<div className="flex flex-col md:flex-row md:gap-4">
  <div className="flex-1">
    - Models
    - Components
    - Remote Sources
  </div>
  <div className="flex-1">
    - Enumerations
    - Taxonomies
  </div>
</div>

You can:

- Select individual elements or entire groups.
- Use **Select full schema** to select every element that is available to import.
- Search within the list to find specific elements.

Models and components often reference other schema elements. When you select an element, Hygraph automatically includes its dependencies when needed.

<Dl>
    <Dt>Plan limits</Dt>
    <Dd>
        Your plan quotas apply to the import. If the selection exceeds limits for models, components, taxonomies, remote sources, or taxonomy nodes, Hygraph blocks those elements or shows a limit alert. Deselect elements or upgrade your plan until the selection fits within your quotas.
    </Dd>
</Dl>

### Step 3: Resolve conflicts

If a selected element uses a display name, `apiId`, `apiIdPlural`, or remote source `prefix` that already exists in your current project, Hygraph treats it as a conflict.

Conflicts are resolved by renaming the schema element you are importing. Your existing schema and content are not modified. You can accept the suggested names or edit them. Related identifiers for the same element are renamed together.

You must resolve all conflicts before you can continue to review.

### Step 4: Review and confirm the import

On the review step, Hygraph calculates the import actions and shows:

- The source project
- How many elements will be created
- Which elements will be created under a new name (**Create & rename**)
- Any plan limit issues that still block the import

Review carefully. Changes apply to your current environment and cannot be undone automatically.

When you are ready, confirm the import. Hygraph creates the selected elements in the target environment. Newly imported elements appear in the schema sidebar when the import completes successfully.

---
# Set up live preview

Source: https://hygraph.com/docs/developer-guides/schema/live-preview

Live preview loads your frontend in a side-by-side iframe inside Studio. Editors open any entry, click **Open live preview**, and see exactly how their unpublished changes look on the actual site, without leaving the entry form.

The preview refreshes when the editor saves the content entry. It does not update in real time as the editor types. Live preview is not compatible with native mobile applications. Requests made by the preview count against your project's rate limits.

<Alert theme="info">
Live preview does not require the Hygraph Preview SDK. Configure your frontend to serve DRAFT content first, then add the Preview widget in Studio with that URL template.
</Alert>

## Create a draft preview token

Your preview URL needs to serve content from Hygraph's `DRAFT` stage. Create a Permanent Auth Token with `DRAFT` as the default stage for preview, and a second token with `PUBLISHED` as the default stage for production. Your application switches between them based on context.

1. Go to **Project Settings > Access > Permanent Auth Tokens**.
2. Click **Add token** and give it a name, for example, `Preview token`.
3. Under **Default stage for content delivery**, click **Change default stage**, and select **Draft**.
4. Click **Initialize defaults**.

Repeat the above steps to create a production token: name it, for example, `Production token`, set the default stage to **Published**, and click **Initialize defaults**. Use this token for live traffic so visitors only receive published content; use the draft preview token only when the preview URL is loaded.

## Choose a preview URL

[Implement your frontend](/docs/developer-guides/schema/live-preview-frontend) so it serves `DRAFT` content for the template you will paste into Studio. Pick the row that matches your frontend and use its URL template in the Preview widget:

| Frameworks | How it works | URL template |
|---|---|---|
| React, Vue, Nuxt, Vanilla JavaScript | The frontend reads `?preview=true` and switches the GraphQL stage for that request. | `https://your-domain.com/{slug}?preview=true` |
| Next.js | Studio hits a preview route that validates a secret, sets a cookie or session, and redirects to the content page. The content page then queries `DRAFT`. | `https://your-domain.com/api/preview?secret=MY_SECRET_TOKEN&slug={slug}` |
| Remix | Studio hits a preview route that validates a secret, sets a cookie or session, and redirects to the content page. The content page then queries `DRAFT`. | `https://your-domain.com/preview?secret=MY_SECRET_TOKEN&slug={slug}` |
| Astro | A separate host or environment always serves `DRAFT`. The URL points at the content page directly. | `https://preview.your-domain.com/{slug}` |

## Add a preview widget

You need to configure the Preview widget once per content model. Use the URL template from [Choose a preview URL](#choose-a-preview-url) that matches your frontend.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmovea1goibsv06w2xaowrhbd" caption="Add a preview widget" />

1. In your Hygraph project, click **Schema**.
2. Select the model you want to enable preview for.
3. Click the **Sidebar** tab at the top of the screen.
4. Select the **Preview** widget from the right sidebar.
5. Complete the **Preview name** and **URL template** fields. Paste the template from your frontend setup. See [Define a preview URL template](#define-a-preview-url-template) for how placeholders such as `{slug}` work.
6. Click **Add**.

If more than one preview URL is required, for example, a local development URL and a staging URL, click **+ Add** to add additional URLs. Editors select between them using a dropdown in the content entry sidebar.

### Define a preview URL template

The URL template tells Studio how to construct the preview link for each entry. It uses your domain plus one or more field values from the content entry as identifiers.

Use curly brace notation to insert field values. As soon as you type `{` in the **URL template** field, Studio shows two groups of available tokens:

**Available fields**: These are the fields on your model. Default system fields available on every model are `id`, `createdAt`, `updatedAt`, `publishedAt`, and `scheduledIn`. Any custom fields you have added to the model, such as `slug`, also appear here.

**Other placeholders**: `{locale}` adds a locale selector to the preview. When your model has more than one locale configured, editors can switch between locales directly in the preview panel. Without it, the switcher does not appear even if your project has multiple locales configured.

**Common patterns:**

```
https://preview.your-domain.com/blog/{slug}
https://your-domain.com/{slug}?preview=true
https://preview.your-domain.com/posts/{id}
https://preview.your-domain.com/{locale}/posts/{slug}
```

Use `{slug}` when your frontend routes by slug. Use `{id}` when it routes by entry ID. You can combine multiple fields and placeholders in a single template if your URL structure requires it.

Framework-specific templates, including redirect routes with a secret token, are listed in [Choose a preview URL](#choose-a-preview-url). Implementation code for each framework is in [Frontend implementation](/docs/developer-guides/schema/live-preview-frontend).

<Alert theme="warning">
If your preview URL serves the PUBLISHED stage, editors will see changes in the preview only after they publish the content entry. The preview will not show any draft content. See [Create a draft preview token](#create-a-draft-preview-token) and [Choose a preview URL](#choose-a-preview-url).
</Alert>

#### Add a secret token

For Next.js and Remix, include a secret in the URL that only your application and Hygraph know. This prevents the preview route, for example `https://your-domain.com/api/preview?secret=MY_SECRET_TOKEN&slug={slug}`, from being accessed directly without going through Studio. React, Vue, Nuxt, Vanilla JavaScript, and Astro URL templates do not require this secret.

<Alert theme="warning">
React, Vue, Nuxt, and Vanilla JavaScript templates use `?preview=true` (or similar) with no secret. Anyone who discovers that URL pattern can view unpublished draft content. For sensitive content, add a secret check like the Next.js and Remix examples, or restrict access to your preview deployment.

Astro uses a separate preview deployment that always serves drafts. Keep that deployment access-restricted (for example behind authentication or your hosting provider's protection).
</Alert>

1. Generate a secret key using a key generator of your choice. Use a strong random string.
2. Replace `MY_SECRET_TOKEN` in the URL template with the generated secret.
3. Add the secret to your app environment as `HYGRAPH_PREVIEW_SECRET` (for example in `.env.local` for Next.js):

    ```bash
    HYGRAPH_PREVIEW_SECRET=MY_SECRET_TOKEN
    ```

Next.js and Remix use a secure cookie or session for preview. For local development over `http://localhost`, you may need to temporarily allow insecure cookies or test against an HTTPS preview URL so the cookie works inside the Studio iframe.

### Add a Variants preview URL

If your model uses [Variants](/docs/developer-guides/schema/variants), you can add one of the variant placeholders, such as `${variant.id}`, `{variant.segments[0].id}`, or `{variant.segments[*].id}`, to your URL template. This lets Studio construct a preview URL that passes the variant or segment ID to your frontend. Editors can preview how content looks for a specific segment before publishing. Without a variant placeholder in the URL template, the variant or segment ID is not passed to the frontend and the preview shows the main entry content only.

You can combine variant placeholders with `{locale}` in the same URL template. Use `{id}` for the entry ID, the same as in a standard preview URL. `${variant.id}` uses a `$` prefix; segment placeholders use curly braces only.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmovgxicbs2bn06w2jpxecr70" caption="Live preview for Variants" />

Ensure you have [added the Preview widget and defined a base URL template](#add-a-preview-widget) before configuring Variants preview.

1. In your Hygraph project, click **Schema** and select the model.
2. Click the **Sidebar** tab.
3. Click **Edit widget** on the Preview widget.
4. Under **Variant preview settings**, complete the **Preview name** and **URL template** fields.
5. Click **Update**.

**Supported URL template tokens for Variants:**

| Token                      | Resolves to                                      |
|----------------------------|--------------------------------------------------|
| `${variant.id}`            | The variant ID                                   |
| `{variant.segments[0].id}` | The first segment ID                             |
| `{variant.segments[*].id}` | All segment IDs, comma-separated and URL-encoded |

**Example URLs and what they resolve to:**

| Approach         | Template                                                                       | Example output                                               |
|------------------|--------------------------------------------------------------------------------|--------------------------------------------------------------|
| By variant ID    | `https://preview.your-domain.com/post/{id}?variant=${variant.id}`              | `.../post/cmeaacg1t...?variant=cmeaacld1...`                 |
| By first segment | `https://preview.your-domain.com/post/{id}?segment={variant.segments[0].id}`   | `.../post/cmeaacg1t...?segment=cmeaafql4...`                 |
| By all segments  | `https://preview.your-domain.com/post/{id}?segments={variant.segments[*].id}`  | `.../post/cmeaacg1t...?segments=cmeaafql4...%2Ccmeaafn9e...` |

`{variant.segments[*].id}` returns all segment IDs as a comma-separated list. Commas are URL-encoded as `%2C`. Your frontend interprets the query parameter and queries the API for the correct variant.

## Verify the setup

1. Open an entry in Studio for the model you configured live preview.
2. In the right sidebar, click **Open live preview**. The preview should load alongside the entry form.
3. Make a change to a field and click **Save & Preview**. The preview should refresh and show your change.

If the preview panel is blank or shows an error, see the [Troubleshooting](#troubleshooting) section.

## Edit or delete a preview URL

1. Navigate to the **Schema** builder and select the model.
2. Next to the **Preview** widget, do one of the following:
    - To edit a preview URL, click the pencil icon, update the **Preview name** or **URL template** fields, and click **Update**.
    - To delete a preview URL, click the trash icon at the end of the row you want to remove.

A preview widget needs to contain at least one URL. If you need to remove the only configured URL, delete the widget from the **Sidebar** tab instead. You can re-add the widget later if needed.

**Delete the preview widget**

![Delete a preview widget](/images/docs/user-guides/live-preview/remove-preview-widget.png)

1. Navigate to the **Schema** builder.
2. Select the model that contains the preview widget that you want to delete.
3. Click on the context menu for the widget, and select `Remove`.

## Troubleshooting

### CSP or security header issues

Your site's security headers are blocking iframe embedding. Check your response headers in your browser's developer tools:
1. Navigate to the **Network** tab.
2. Search for the page you are trying to see.
3. Under the **Headers** subtab, click the **Response Headers**.
4. Determine whether the security configuration matches one of the options below:
    - If `X-Frame-Options` is set, remove it from your application.
    - If `Content-Security-Policy` is set, add `frame-ancestors 'self' https://*.hygraph.com` to the header value.

If you are hosting on Vercel, go to **Settings > Deployment Protection** and disable **Vercel Authentication**. This removes the `X-Frame-Options` header. Disabling Vercel Authentication makes preview deployments publicly accessible.

### Stale data

Your frontend is serving the `PUBLISHED` stage in preview. Check that:

- Your preview token has `DRAFT` set as the default content stage.
- Your application is using the preview token, not the production token, when the preview URL is loaded.
- Your GraphQL queries are not hardcoding `stage: PUBLISHED`.
- You do not have a caching layer active in preview mode.

### No Open live preview button

The entry should have been saved at least once, that is, it should exist in the `DRAFT` stage. The button does not appear on unsaved entries.

## What's next

- [Click to Edit setup](/docs/developer-guides/schema/click-to-edit): Learn how to install the Hygraph Preview SDK and configure Click to Edit so editors can jump from any preview element directly to the corresponding field in Hygraph Studio.

---
# Live preview - Frontend implementation

Source: https://hygraph.com/docs/developer-guides/schema/live-preview-frontend

Live preview requires your frontend to serve content from the Hygraph `DRAFT` stage when loaded inside Studio's preview iframe. This page covers how to implement that for React, Next.js, Remix, Vue, Nuxt, Astro, and vanilla JavaScript.

**Ways to query the DRAFT stage**

- Create a URL for your web app that queries the `DRAFT` stage of your endpoint. This could look like: `https://preview.yourwebsite.com`. You could also use a query parameter on the URL, like this: `https://yourwebsite.com?preview=true`.
- Create a Permanent Auth Token that returns the `DRAFT` stage for the preview environment.
- Change from `PUBLISHED` to `DRAFT` in your app based on a preview context inside your frontend.

## Prerequisites

- A Permanent Auth Token that returns the `DRAFT` stage for the preview environment. Create one in [Set up live preview](/docs/developer-guides/schema/live-preview#create-a-draft-preview-token).
- Your High Performance Content API endpoint.
  - Find it under **Project Settings > Access > Endpoints > High Performance Content API** in your Hygraph project.

URL templates to paste into the Studio Preview widget are listed in [Choose a preview URL](/docs/developer-guides/schema/live-preview#choose-a-preview-url). Each framework section below includes the matching template.

## Next.js

Next.js uses the `draftMode` API from `next/headers` to toggle between `DRAFT` and `PUBLISHED` content. A preview route sets the draft mode cookie; your page components read `isEnabled` to decide which stage to query. Use this URL template in Studio: `https://your-domain.com/api/preview?secret=MY_SECRET_TOKEN&slug={slug}`.

<Alert theme="warning">
In Next.js 13 and later, the `draftMode` cookie is set with `SameSite=Lax` by default, which prevents it from working inside an iframe. The route handler below applies a workaround that sets `SameSite=None` after enabling draft mode. The cookie is also marked `secure`, so local preview over `http://localhost` may not persist the cookie inside the Studio iframe. Prefer an HTTPS preview URL for iframe testing.
</Alert>

### Step 1: Create the preview route handler

Create `app/api/preview/route.ts`. This route validates the secret token and slug, enables draft mode, and redirects to the correct page.

```ts
// app/api/preview/route.ts
import { draftMode, cookies } from 'next/headers';
import { redirect } from 'next/navigation';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const secret = searchParams.get('secret');
  const slug = searchParams.get('slug');

  // Check the secret against the value configured in your environment
  if (secret !== process.env.HYGRAPH_PREVIEW_SECRET || !slug) {
    return new Response('Invalid token', { status: 401 });
  }

  // Fetch the slug from Hygraph to ensure we don't run into redirect loops
  const res = await fetch(process.env.HYGRAPH_ENDPOINT!, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.HYGRAPH_PREVIEW_TOKEN}`,
    },
    body: JSON.stringify({
      query: `
        query SinglePage($slug: String!) {
          page(where: { slug: $slug }, stage: DRAFT) {
            slug
          }
        }
      `,
      variables: { slug },
    }),
  });

  const { data } = await res.json();

  if (!data?.page) {
    return new Response('Invalid slug', { status: 401 });
  }

  // Workaround for https://github.com/vercel/next.js/issues/49927
  // Enable draft mode as usual (await required in Next.js 15+)
  const draft = await draftMode();
  draft.enable();

  // Update the cookie and set SameSite=None so it works inside the Hygraph iframe
  const cookieStore = await cookies();
  const cookie = cookieStore.get('__prerender_bypass');
  cookieStore.set({
    name: '__prerender_bypass',
    value: cookie?.value,
    httpOnly: true,
    path: '/',
    secure: true,
    sameSite: 'none',
  });

  redirect(`/${data.page.slug}`);
}
```

### Step 2: Query DRAFT or PUBLISHED based on draft mode

In your page component, read `isEnabled` from `draftMode()` to switch between stages.

```ts
// app/[slug]/page.tsx
import { request } from 'graphql-request';
import { draftMode } from 'next/headers';

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  // isEnabled is true if the draft mode cookie has been set by the preview route
  // See: https://nextjs.org/docs/app/building-your-application/configuring/draft-mode
  const { slug } = await params;
  const { isEnabled } = await draftMode();

  // Default stage is PUBLISHED. Switch to DRAFT when draft mode is active.
  const query = `
    query Page($slug: String!, $stage: Stage! = PUBLISHED) {
      page(where: { slug: $slug }, stage: $stage) {
        title
        description
        slug
      }
    }
  `;

  const variables = {
    stage: isEnabled ? 'DRAFT' : 'PUBLISHED',
    slug,
  };

  // Use the preview token in draft mode so the DRAFT stage is accessible,
  // and the production token otherwise so only PUBLISHED content is served
  const endpoint = process.env.HYGRAPH_ENDPOINT!;
  const token = isEnabled
    ? process.env.HYGRAPH_PREVIEW_TOKEN!
    : process.env.HYGRAPH_PRODUCTION_TOKEN!;

  const { page } = await request(endpoint, query, variables, {
    Authorization: `Bearer ${token}`,
  });

  return (
    <main>
      <h1>{page.title}</h1>
      <p>{page.description}</p>
    </main>
  );
}
```

### Step 3: Configure Next.js environment variables

```bash
# .env.local
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
HYGRAPH_PREVIEW_SECRET=MY_SECRET_TOKEN
```

For a full implementation including more complex content models, see the <Link href="https://hygraph.com/marketplace/starters/skncre-starter-next" target="_blank">SKNCRE Cosmetics Shop Starter</Link>.

## React

For a client-side React app, such as Vite, Create React App, with no server of its own, route the preview request through a serverless function instead of calling Hygraph directly from the browser. This keeps your Permanent Auth Token off the client. Use this URL template in Studio: `https://your-domain.com/{slug}?preview=true`.

<Alert theme="warning">
Anyone who discovers this URL pattern can view your draft content. For sensitive content, add a secret check like the Next.js or Remix examples do, or restrict access to your preview deployment.
</Alert>

### Step 1: Create a React serverless preview function

Deploy a serverless function (for example, a Vercel or Netlify function) that picks the stage and token based on a `preview` flag, then queries Hygraph.

Do not prefix `HYGRAPH_PREVIEW_TOKEN` or `HYGRAPH_PRODUCTION_TOKEN` with `VITE_`, `REACT_APP_`, or any build-tool prefix that exposes variables to the browser bundle. Only the serverless function needs them.

```js
// api/preview.js
export default async function handler(req, res) {
  const { slug, preview } = req.query;
  const isPreview = preview === 'true';
  const stage = isPreview ? 'DRAFT' : 'PUBLISHED';
  const token = isPreview
    ? process.env.HYGRAPH_PREVIEW_TOKEN
    : process.env.HYGRAPH_PRODUCTION_TOKEN;

  const query = `
    query Page($slug: String!, $stage: Stage!) {
      page(where: { slug: $slug }, stage: $stage) {
        title
        description
        slug
      }
    }
  `;

  const response = await fetch(process.env.HYGRAPH_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ query, variables: { slug, stage } }),
  });

  const { data } = await response.json();
  res.status(200).json(data.page);
}
```

### Step 2: Call the proxy from your React page

Read the `preview` query parameter and pass it through to your function. The component never touches the Hygraph endpoint or token directly.

```jsx
// src/Page.jsx
import { useEffect, useState } from 'react';
import { useParams, useSearchParams } from 'react-router-dom';

export default function Page() {
  const { slug } = useParams();
  const [searchParams] = useSearchParams();
  const isPreview = searchParams.get('preview') === 'true';
  const [page, setPage] = useState(null);

  useEffect(() => {
    fetch(`/api/preview?slug=${slug}&preview=${isPreview}`)
      .then((res) => res.json())
      .then(setPage);
  }, [slug, isPreview]);

  if (!page) return null;

  return (
    <main>
      <h1>{page.title}</h1>
      <p>{page.description}</p>
    </main>
  );
}
```

### Step 3: Configure React environment variables

Set these on the serverless function's host, not in a client-exposed `.env` file.

```bash
# Serverless function environment
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
```

For click-to-edit overlays on top of this preview flow, see [Click to Edit setup](/docs/developer-guides/schema/click-to-edit).

## Remix

Remix runs loaders on the server, so you can use a cookie-backed session to persist preview state across requests, the same way the Next.js route handler above uses a cookie. Use this URL template in Studio: `https://your-domain.com/preview?secret=MY_SECRET_TOKEN&slug={slug}`.

The session cookie uses `sameSite: 'none'` and `secure: true` so it works inside the Studio iframe. Local preview over `http://localhost` may not persist that cookie; prefer an HTTPS preview URL for iframe testing.

### Step 1: Create a session for preview state

```ts
// app/sessions.server.ts
import { createCookieSessionStorage } from '@remix-run/node';

export const { getSession, commitSession } = createCookieSessionStorage({
  cookie: {
    name: '__preview_mode',
    secrets: [process.env.HYGRAPH_PREVIEW_SECRET!],
    secure: true,
    sameSite: 'none', // required so the cookie works inside the Studio preview iframe
    path: '/',
    httpOnly: true,
  },
});
```

### Step 2: Create the preview resource route

This route validates a secret token, sets the session, and redirects to the page.

```ts
// app/routes/preview.tsx
import { redirect, type LoaderFunctionArgs } from '@remix-run/node';
import { getSession, commitSession } from '~/sessions.server';

export async function loader({ request }: LoaderFunctionArgs) {
  const url = new URL(request.url);
  const slug = url.searchParams.get('slug');
  const secret = url.searchParams.get('secret');

  if (!slug || secret !== process.env.HYGRAPH_PREVIEW_SECRET) {
    throw new Response('Invalid token', { status: 401 });
  }

  const session = await getSession(request.headers.get('Cookie'));
  session.set('isPreview', true);

  return redirect(`/${slug}`, {
    headers: { 'Set-Cookie': await commitSession(session) },
  });
}
```

### Step 3: Query DRAFT or PUBLISHED in the page loader

```ts
// app/routes/$slug.tsx
import { json, type LoaderFunctionArgs } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { getSession } from '~/sessions.server';

export async function loader({ request, params }: LoaderFunctionArgs) {
  const session = await getSession(request.headers.get('Cookie'));
  const isPreview = session.get('isPreview') === true;

  const stage = isPreview ? 'DRAFT' : 'PUBLISHED';
  const token = isPreview
    ? process.env.HYGRAPH_PREVIEW_TOKEN
    : process.env.HYGRAPH_PRODUCTION_TOKEN;

  const query = `
    query Page($slug: String!, $stage: Stage!) {
      page(where: { slug: $slug }, stage: $stage) {
        title
        description
        slug
      }
    }
  `;

  const res = await fetch(process.env.HYGRAPH_ENDPOINT!, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ query, variables: { slug: params.slug, stage } }),
  });

  const { data } = await res.json();
  return json({ page: data.page });
}

export default function Slug() {
  const { page } = useLoaderData<typeof loader>();

  return (
    <main>
      <h1>{page.title}</h1>
      <p>{page.description}</p>
    </main>
  );
}
```

### Step 4: Configure Remix environment variables

```bash
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
HYGRAPH_PREVIEW_SECRET=your-secret-token
```

For click-to-edit overlays on top of this preview flow, see [Click to Edit - Remix](/docs/developer-guides/schema/click-to-edit-remix).

## Vue

For a client-side Vue 3 app with Vue Router (no Nuxt), route the preview request through a serverless function instead of calling Hygraph directly from the browser. This keeps your Permanent Auth Token off the client. Use this URL template in Studio: `https://your-domain.com/{slug}?preview=true`.

<Alert theme="warning">
Anyone who discovers this URL pattern can view your draft content. For sensitive content, add a secret check like the Next.js or Remix examples do, or restrict access to your preview deployment.
</Alert>

### Step 1: Create a Vue serverless preview function

Deploy a serverless function (for example, a Vercel or Netlify function) that picks the stage and token based on a `preview` flag, then queries Hygraph.
Do not prefix `HYGRAPH_PREVIEW_TOKEN` or `HYGRAPH_PRODUCTION_TOKEN` with `VITE_` or any build-tool prefix that exposes variables to the browser bundle. Only the serverless function needs them.

```js
// api/preview.js
export default async function handler(req, res) {
  const { slug, preview } = req.query;
  const isPreview = preview === 'true';
  const stage = isPreview ? 'DRAFT' : 'PUBLISHED';
  const token = isPreview
    ? process.env.HYGRAPH_PREVIEW_TOKEN
    : process.env.HYGRAPH_PRODUCTION_TOKEN;

  const query = `
    query Page($slug: String!, $stage: Stage!) {
      page(where: { slug: $slug }, stage: $stage) {
        title
        description
        slug
      }
    }
  `;

  const response = await fetch(process.env.HYGRAPH_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ query, variables: { slug, stage } }),
  });

  const { data } = await response.json();
  res.status(200).json(data.page);
}
```

### Step 2: Call the proxy from your Vue page

Read the `preview` query parameter and pass it through to your function. The component never touches the Hygraph endpoint or token directly.

```vue
<!-- src/views/Page.vue -->
<script setup>
import { ref, onMounted } from 'vue';
import { useRoute } from 'vue-router';

const route = useRoute();
const isPreview = route.query.preview === 'true';
const page = ref(null);

onMounted(async () => {
  const res = await fetch(
    `/api/preview?slug=${route.params.slug}&preview=${isPreview}`
  );
  page.value = await res.json();
});
</script>

<template>
  <main v-if="page">
    <h1>{{ page.title }}</h1>
    <p>{{ page.description }}</p>
  </main>
</template>
```

### Step 3: Configure Vue environment variables

Set these on the serverless function's host, not in a client-exposed `.env` file.

```bash
# Serverless function environment
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
```

Running Nuxt instead of plain Vue? Use the [Nuxt](#nuxt) section below. It queries Hygraph server-side, so it doesn't need the proxy function.

For click-to-edit overlays on top of this preview flow, see [Click to Edit - Vue / Nuxt](/docs/developer-guides/schema/click-to-edit-vue-nuxt).

## Nuxt

Nuxt uses a plugin to detect a `?preview=true` query parameter and expose a global `$preview` variable. Keep Hygraph tokens in server-only runtime config, and query Hygraph from a server API route so client-side navigation still works. Use this URL template in Studio: `https://your-domain.com/{slug}?preview=true`.

<Alert theme="warning">
Anyone who discovers this URL pattern can view your draft content. For sensitive content, add a secret check like the Next.js or Remix examples do, or restrict access to your preview deployment.
</Alert>

### Step 1: Create the Nuxt preview plugin

Create `/plugins/preview.ts`. Nuxt reads this automatically on startup.

```ts
// plugins/preview.ts
export default defineNuxtPlugin((nuxtApp) => {
  const route = useRoute();

  // Refresh page data when navigating while ?preview=true is present
  nuxtApp.hook('page:finish', () => {
    if (route.query.preview === 'true') {
      refreshNuxtData();
    }
  });

  // Expose a reactive $preview flag for templates and page logic
  return {
    provide: {
      preview: computed(() => route.query.preview === 'true'),
    },
  };
});
```

The plugin refreshes page data after in-app navigation in preview mode. `$preview` stays in sync with the current route query.

For more ways to configure Nuxt preview mode, see the <Link href="https://nuxt.com/docs/api/composables/use-preview-mode" target="_blank">Nuxt usePreviewMode documentation</Link>.

### Step 2: Configure Nuxt runtime config

Keep Hygraph tokens server-side. Add them to private `runtimeConfig` in `nuxt.config.ts`. Only server routes can read these values and they are empty in the browser.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    hygraphEndpoint: process.env.HYGRAPH_ENDPOINT,
    hygraphPreviewToken: process.env.HYGRAPH_PREVIEW_TOKEN,
    hygraphProductionToken: process.env.HYGRAPH_PRODUCTION_TOKEN,
  },
});
```

### Step 3: Create a Nuxt server API route

Move the Hygraph query into `server/api/` so tokens stay on the server during SSR and client-side navigation.

```ts
// server/api/page.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const slug = String(query.slug ?? '');
  const isPreview = query.preview === 'true';
  const config = useRuntimeConfig();

  const stage = isPreview ? 'DRAFT' : 'PUBLISHED';
  const token = isPreview
    ? config.hygraphPreviewToken
    : config.hygraphProductionToken;

  const graphqlQuery = `
    query Page($slug: String!, $stage: Stage! = PUBLISHED) {
      page(where: { slug: $slug }, stage: $stage) {
        title
        description
      }
    }
  `;

  const response = await $fetch<{ data: { page: { title: string; description: string } } }>(
    config.hygraphEndpoint,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
      body: {
        query: graphqlQuery,
        variables: { slug, stage },
      },
    }
  );

  return response.data.page;
});
```

### Step 4: Call the API route from the Nuxt page

Use `useFetch` so the page works on first load and on in-app navigation without exposing tokens to the browser.

```vue
<!-- pages/[slug].vue -->
<script setup>
const route = useRoute();

const { data: page } = await useFetch('/api/page', {
  query: computed(() => ({
    slug: route.params.slug,
    preview: route.query.preview === 'true' ? 'true' : 'false',
  })),
});
</script>

<template>
  <main v-if="page">
    <h1>{{ page.title }}</h1>
    <p>{{ page.description }}</p>
  </main>
</template>
```

### Step 5: Configure Nuxt environment variables

```bash
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
```

For a full Nuxt implementation, see the <Link href="https://hygraph.com/marketplace/starters/skncre-starter" target="_blank">SKNCRE Cosmetics Shop Starter</Link>.

## Astro

Astro is focused on Static Site Generation (SSG) and due to its incredible flexibility in terms of using frontend frameworks, Astro does not have a built-in preview mode like Next.js or Nuxt. Static generation caches responses, which means editors will always see stale content in preview. You can configure the Astro site to run in SSR (server-side rendered) mode and use an environment variable to switch the query stage. Use this URL template in Studio: `https://preview.your-domain.com/{slug}`.

<Alert theme="warning">
This setup always serves draft content on the preview host. Keep the preview deployment access-restricted (for example behind authentication or your hosting provider's protection).
</Alert>

### Step 1: Enable SSR in the Astro config

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  // SSR is required — static generation caches responses and editors
  // will always see stale content in preview without it
  output: 'server',
  adapter: vercel(), // or node, netlify, cloudflare
});
```

Other adapters (`node`, `netlify`, `cloudflare`) are supported. The key requirement is `output: 'server'`.

### Step 2: Read the Astro preview environment variable in pages

```astro
---
// src/pages/[slug].astro
import { request } from 'graphql-request';

// HYGRAPH_PREVIEW=true is set in your preview deployment environment only.
// Do not set this in production — it would serve DRAFT content to all visitors.
const isPreview = import.meta.env.HYGRAPH_PREVIEW === 'true';

// Default stage is PUBLISHED. Switch to DRAFT in the preview deployment.
const query = `
  query Page($slug: String!, $stage: Stage! = PUBLISHED) {
    page(where: { slug: $slug }, stage: $stage) {
      title
      description
    }
  }
`;

const variables = {
  stage: isPreview ? 'DRAFT' : 'PUBLISHED',
  slug: Astro.params.slug,
};

const token = isPreview
  ? import.meta.env.HYGRAPH_PREVIEW_TOKEN
  : import.meta.env.HYGRAPH_PRODUCTION_TOKEN;

const { page } = await request(
  import.meta.env.HYGRAPH_ENDPOINT,
  query,
  variables,
  { Authorization: `Bearer ${token}` }
);
---

<html>
  <head><title>{page.title}</title></head>
  <body>
    <main>
      <h1>{page.title}</h1>
      <p>{page.description}</p>
    </main>
  </body>
</html>
```

### Step 3: Configure Astro environment variables

Set `HYGRAPH_PREVIEW=true` in your preview environment, such as Vercel or Netlify. Do not set it in your production environment. The `true` value matches the `preview=true` convention used by the other frameworks.

```bash
# Preview environment only
HYGRAPH_PREVIEW=true
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
```

```bash
# Production environment
HYGRAPH_PREVIEW=false
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
```

For a full Astro implementation, see the <Link href="https://hygraph.com/marketplace/starters/skncre-starter-astro" target="_blank">SKNCRE Cosmetics Shop Starter</Link>. That starter may still show an older `HYGRAPH_IS_PREVIEW` name; use `HYGRAPH_PREVIEW=true` as shown above for consistency with the other frameworks. For live Studio preview after save, use SSR as shown above rather than static generation.

## Vanilla JavaScript

For frontend applications without a framework, run a minimal Node.js server that reads the preview signal from the request and switches the GraphQL query stage before rendering HTML. Keep the Permanent Auth Token server-side only, since a token embedded in client-side JavaScript is visible in DevTools to anyone who opens it. Treat it like a secret and do not expose it to the client. Use this URL template in Studio: `https://your-domain.com/{slug}?preview=true`.

<Alert theme="warning">
Anyone who discovers this URL pattern can view your draft content. For sensitive content, add a secret check like the Next.js or Remix examples do, or restrict access to your preview deployment.
</Alert>

### Step 1: Read the preview query parameter and switch stage

Check for `?preview=true` on the incoming request, then pick the stage and token before querying Hygraph.

```js
// server.js
import express from 'express';
import fetch from 'node-fetch';

const app = express();

async function fetchPage(slug, isPreview) {
  const stage = isPreview ? 'DRAFT' : 'PUBLISHED';
  const token = isPreview
    ? process.env.HYGRAPH_PREVIEW_TOKEN
    : process.env.HYGRAPH_PRODUCTION_TOKEN;

  const query = `
    query Page($slug: String!, $stage: Stage!) {
      page(where: { slug: $slug }, stage: $stage) {
        title
        description
        slug
      }
    }
  `;

  const res = await fetch(process.env.HYGRAPH_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ query, variables: { slug, stage } }),
  });

  const { data } = await res.json();
  return data.page;
}

app.get('/:slug', async (req, res) => {
  const isPreview = req.query.preview === 'true';
  const page = await fetchPage(req.params.slug, isPreview);

  res.send(`
    <html>
      <body>
        <h1>${page.title}</h1>
        <p>${page.description}</p>
      </body>
    </html>
  `);
});

app.listen(3000);
```

### Step 2: Configure Vanilla JavaScript environment variables

```bash
HYGRAPH_ENDPOINT=https://your-region.cdn.hygraph.com/content/your-project-id/master
HYGRAPH_PREVIEW_TOKEN=your-draft-stage-token
HYGRAPH_PRODUCTION_TOKEN=your-published-stage-token
```

The route reads `preview` on each request and queries `DRAFT` only for that request. Visitors without the parameter get `PUBLISHED` content.

For a full implementation including the Hygraph Preview SDK for click-to-edit overlays, see [Click to Edit - Vanilla JavaScript](/docs/developer-guides/schema/click-to-edit-vanilla-js).

## What's next

- [Live preview](/docs/developer-guides/schema/live-preview): Configure live preview so editors can see draft content rendered in your frontend before publishing.
- [Get started with Click to Edit](/docs/developer-guides/schema/click-to-edit): Add SDK-powered edit buttons on top of a live preview.


---
# Models

Source: https://hygraph.com/docs/developer-guides/schema/models

A **model** defines the structure of a content type in your project. The models you create and the [fields](/docs/api-reference/schema/field-types) you add make up your schema. Hygraph exposes models and their fields in the GraphQL API as soon as you save it. Content editors then create entries based on those models in the Content editor.

<Alert theme="info" title="Looking for the API Reference?">

For GraphQL operations generated from models and programmatic schema management, see the [Models API Reference](/docs/api-reference/schema/models).

</Alert>

Every Hygraph project includes the following system models:

| Model | Purpose |
| --- | --- |
| **Asset** | Stores images and other files. You can add fields to it, but you cannot delete it. |
| **Query** | Used to configure top-level remote fields. You cannot delete it. |
| **Segment** | A named reference used to target a group of users for [Variants](/docs/developer-guides/schema/variants). You can add fields to it, but you cannot delete it or localize its fields. |

You can create custom models for the rest of your content types. Schema changes are available in the GraphQL API as soon as you save them.

## Create a model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmkc6mce6w7w407vzxb6vyz2v" caption="Create a model" />

1. Navigate to the **Schema** builder.
2. In the Schema list, click **+ Add** next to **Models**. Or, if you're adding a model for the first time, click **+ Add Model** in the center of the screen.
3. Complete the model settings:

    | Property | Example | Description |
    | --- | --- | --- |
    | Display name | `Post` | The name shown in Hygraph for content editors. |
    | API ID | `Post` | The ID used to fetch a single entry through the API. |
    | Plural API ID | `Posts` | The ID used to fetch multiple entries through the API. |
    | Description | `Blog posts` | Optional hint for editors working with this model. |

    Hygraph auto-fills **API ID** and **Plural API ID** from the display name. You can edit them before you save. Avoid [reserved terms](/docs/developer-guides/schema/reserved-terms).

4. Click **Add Model**.

Your model appears in the Schema list. It has no custom fields yet. Next, [add fields](/docs/developer-guides/schema/models#add-fields-to-a-model) to define what editors can enter.

## Add fields to a model

Fields define the data a model can store. Each field uses one of Hygraph’s supported [field types](/docs/api-reference/schema/field-types).

1. Open the model in the Schema builder.
2. From the **Add fields** sidebar, select a field type.
3. Configure the field display name, API ID, and any options or [validations](/docs/api-reference/schema/field-configuration#validations).
4. Click **Add**.

You can add fields to custom models and to the system **Asset** model.

Useful field guides:

- [Field types](/docs/api-reference/schema/field-types) — available field types and what they store
- [Field configuration](/docs/api-reference/schema/field-configuration) — options, validations, and advanced settings
- [Slug field](/docs/developer-guides/schema/slug-field) — generate slugs from other field values
- [Conditional fields](/docs/developer-guides/schema/conditional-fields) — show or hide fields based on other values
- [References](/docs/developer-guides/schema/references) — relate entries across models
- [Components](/docs/developer-guides/schema/components) — reuse groups of fields inside a model

### System fields

Every model includes [system fields](/docs/api-reference/schema/system-fields) such as `id`, `createdAt`, `updatedAt`, and `publishedAt`. You do not need to add them; Hygraph manages them automatically.

To view system fields on a model, enable **Show system fields** in the **Fields** tab.

## Edit a model

1. Navigate to the **Schema** builder.
2. Select the model you want to edit.
3. Open the model settings (context menu) to update the display name, API IDs, description, or [preview URLs](#preview-urls).

Changing API IDs after content exists can break existing queries and integrations. Plan renames carefully.

## Delete a model

1. Navigate to the **Schema** builder.
2. Select the model you want to delete.
3. Open the context menu and choose **Delete**.

Deleting a model also deletes all of its content entries. System models (**Asset**, **Query**, and **Segment**) cannot be deleted.

## Preview URLs

Preview URLs let editors open a frontend preview of an entry from the Content editor. They are most useful for models that represent a page and include a field such as a slug.

Configure preview URLs in the model settings. You can use fields from the model in the URL template. For example, a `Post` model might use:

| Preview name | URL template |
| --- | --- |
| Production | `https://example.com/blog/{slug}` |
| Staging | `https://staging.example.com/blog/{slug}` |
| Next.js Preview | `https://example.com/api/preview?secret=abc&slug={slug}` |

For live preview and visual editing setup, see [Visual editing](/docs/developer-guides/schema/visual-editing-overview).

## Next steps

After your models are in place, you can:

- [Import schema elements from another project](/docs/developer-guides/schema/import-schema)
- Connect models with [references](/docs/developer-guides/schema/references)
- Reuse field groups with [components](/docs/developer-guides/schema/components)
- Add constrained options with [enumerations](/docs/developer-guides/schema/using-enumerations)
- Classify content with [taxonomies](/docs/developer-guides/schema/taxonomies)
- Follow a full modeling walkthrough in the [content models tutorial](/docs/getting-started/tutorial/tutorial-content-models-overview)


---
# Recently viewed

Source: https://hygraph.com/docs/developer-guides/schema/recently-viewed

## Overview

Editors often work in projects with a lot of content views and content entries. Hygraph offers a way to quickly go back to content entries that they recently accessed or edited.

This feature increases editor productivity and saves time by providing shortcuts to recently viewed content. It is designed to make finding content easier, preventing Editors from having rely on memory or search through different content views to find a recently accessed content entry.

## Access

You can access a menu with shortcuts to your recently viewed content entries by clicking on the clock icon in the top bar.

![Recently viewed menu access](/images/docs/user-guides/recently-viewed-access.png)

<Alert theme="info" title="Pro Tip">

This information is also available in the recently viewed section of the [command menu](/docs/developer-guides/schema/command-menu#recently-viewed). To find this section, press `CMD+K` (or `CTRL+K` in Windows), and type “Recently” in the search. If you are in the Content editor when using the command menu, this section will be at the top of the list.

</Alert>

## Usage

Simply click on one of the entries to open it in the content editor. Optionally, you can use your keyboard to select an entry and press enter.

The content form of the selected entry will open in the same tab.

![Recently viewed menu](/images/docs/user-guides/recently-viewed-menu.png)

The list of up to 30 content entries will display sorted by recency, with the most recent entries showing at the top.

It shows all recently viewed entries including the ones that were opened from inside a content form, such as an `Author` entry opened from the `Book` entry.

Please note:

- The list only shows the entries viewed by the current user.
- It is project & environment specific: Users can only see entries in the project and in the environment that they're currently viewing.
- Users can see recently viewed entries **dating back up to one month**.

## Limitations

### Search

There is no search available in the recently viewed menu. However, if you check the recently viewed section of the [command menu](/docs/developer-guides/schema/command-menu#recently-viewed), you can to use the search there to find a content entry.

### Inaccessible entry

If a user tries to open an inaccessible entry (due to removal or permission loss), an error message displays.

- **Entry removal:** The user sees a message indicating that the entry cannot be found.
- **Permission loss:** The user sees a message indicating that they do not have permission to view the entry.





---
# References

Source: https://hygraph.com/docs/developer-guides/schema/references

Reference fields connect content entries across models. Choosing the wrong direction or cardinality requires deleting and rebuilding the field, so plan your schema before you start.

## Add a reference field

1. Go to **Schema** and select the model you want to update.
2. From the **Field types** sidebar, select **Reference**.
3. On the [**Define**](#define-tab) tab, set the reference type, model to reference, reference direction, and relation cardinality. These settings cannot be changed after saving.
4. On the [**Configure**](#configure-tab) tab, set the display name, API ID, and any behavior options.
5. If you selected a two-way reference, configure the reverse field on the [**Reverse field**](#reverse-field-tab) tab.
6. Click **Add**.

The sections below describe each tab and its options in detail.

## Define tab

The **Define** tab controls the structural decisions that cannot be changed after the field is saved.

<Alert theme="warning" title="Define tab settings cannot be changed after saving">
    Reference type, model to reference, reference direction, and relation cardinality are all locked after you click **Add**. For Union Type fields, you can edit which models are included in the relation after the initial save, but you cannot change the other settings. Delete and recreate the field to change any other locked setting.
</Alert>

### Reference type

Use the **Reference type** radio buttons to control how many models this field can point to.

- **Allow only one model to be referenced**: The field returns content from one model. One-way or two-way reference direction is available.
- **Allow multiple models to be referenced (Union Type)**: The field returns content from multiple models. Only two-way reference direction is available; one-way is disabled.

### Model to reference

Select the models this field will reference. The **Relation cardinality** controls appear below after you make a selection.

### Reference direction

- **One-way reference**: The field is queryable only from the model where you add it. The referenced model has no reverse field.
    - For example, a **Post** referencing an **Author** one-way means editors can select an author from the `Post` entry, but opening an `Author` entry shows no list of connected posts.
- **Two-way reference**: Hygraph adds a reverse field to the referenced model, making the relation queryable from both sides.
    - For example, a **Post** referencing an **Author** two-way means editors can see connected posts from the `Author` entry as well. This also adds the **Reverse field** tab to the modal.

### Relation cardinality

Relation cardinality controls how many entries can be connected on each side of the relation. Use the dropdown in the center of the diagram to set this. The checkboxes below the diagram reflect your selection and update automatically.

**One-way reference**

| Option | Meaning | Example |
|--------|---------|---------|
| One to one | One entry in this model links to exactly one entry in the referenced model | A country links to one capital city |
| One to many | One entry in this model links to multiple entries in the referenced model | An author links to multiple posts |

**Two-way reference**

| Option | Meaning | Example |
|--------|---------|---------|
| One to one | One entry on each side links to exactly one entry on the other side | Each country has one capital city and each capital city belongs to only one country |
| One to many | One entry in this model links to multiple entries in the referenced model | An author links to multiple posts, and each post belongs to only one author |
| Many to one | Multiple entries in this model link to one entry in the referenced model | Multiple reviews link to one product, and each review belongs to only one product |
| Many to many | Multiple entries on both sides can be connected | A product belongs to many categories and a category contains many products |

## Configure tab

The **Configure** tab sets the field's display name, API ID, and behavior options. These settings can be updated after the field is created.

### Display name and API ID

Hygraph pre-populates **Display name** and **API ID** based on your Define tab selections. You can change them before saving.

### Description

**Description** is optional. The text you enter here displays as a hint for content editors and API users.

### Validation

The validation option available depends on the cardinality you selected on the **Define** tab. These validations apply in the UI only and are intended to help editors remember to connect entries. Keep the following in mind:

- Unlike other [required fields](/docs/api-reference/schema/field-configuration#make-field-required), the API does not enforce these validations. Content can be saved or published via the API regardless of validation state.
- If a referenced entry is deleted, or disconnected from the other side of a two-way reference, Hygraph removes the link automatically but does not display an error. For example, if an Article requires a linked Product and someone deletes that Product, the Article loses the connection silently with no error shown.
- If an editor removes a connected entry from the content form, the warning appears and blocks publishing until the requirement is met.
- An entry that exists as a draft but has not been published still counts as connected.

<Dl>
    <Dt>One to one and Many to one</Dt>
    <Dd>
        **Require a connected entry** displays an editorial warning in the content form if no entry is linked. Unlike other [required fields](/docs/api-reference/schema/field-configuration#make-field-required), the API does not enforce this requirement. You can optionally add a **Custom error message** to replace the default warning text.
    </Dd>
    <Dt>One to many and Many to many</Dt>
    <Dd>
        **Limit connected entry count** specifies a minimum and/or maximum number of connected entries upon saving or publishing the entry. Use the dropdown to set the constraint type:

        | Option | Inputs required |
        |--------|----------------|
        | Between | Min and Max |
        | At least | Min only |
        | Not more than | Max only |

        You can optionally add a **Custom error message** to replace the default validation text.
    </Dd>
</Dl>

### Enable variants

**Enable variants** lets this reference field hold different values for each Variant of a content entry. Editors can set a different connected entry per Variant without affecting the main entry or other Variants. This option is not available for unique fields. Disabling it after content has been created removes the field and its values from all Variants. Variants are an enterprise feature; see the [Variants documentation](/docs/developer-guides/schema/variants) for setup details.

### Show based on condition

**Show based on condition** lets you configure conditional visibility so the field only appears in the content form when a specified condition is met. Select an Enumeration or Boolean field from this model to establish the condition.

### Field visibility

**Field visibility** controls how the field appears in the UI and API. **Read / Write** is selected by default.

| Option | Behavior |
|--------|----------|
| Read / Write | Field can be read and edited |
| Read only | Field is shown but cannot be edited in the UI; editable through the API only |
| Hidden | Field is not shown in the UI; other fields can still reference it |
| API only | Field is not shown in the UI; readable and editable through the API only |

If you selected a one-way reference, click **Add** to save the field. If you selected a two-way reference, continue to the **Reverse field** tab.

## Reverse field tab

The **Reverse field** tab appears only for two-way references. It configures the field that Hygraph adds to the referenced model.

Hygraph pre-populates **Display name** and **API ID** from the referenced model name. You can change them before saving. **Field visibility** defaults to **API only** for the reverse field.

Click **Add** to add the field to the model.

To make further configuration changes to the reverse field after saving, navigate to the referenced model and edit the field. A banner displays which model the reverse field belongs to, for example, "Field in **Article** referencing **Product**". Click **Visit model** to open that model directly.

## What's next

- [Fetch relations](/docs/api-reference/content-api/queries#fetching-relations): Learn how to query connected entries via the Content API.
- [Create references](/docs/editor-guides/content/create-references): Learn how to connect entries to one another directly from the content editor.
- [Duplicate content](/docs/developer-guides/content/duplicating-content): See how relational field types behave when content entries are duplicated.
- [Components or references](/docs/developer-guides/schema/components-or-references): Understand when to use a component versus a reference for related content.


---
# Reserved terms

Source: https://hygraph.com/docs/developer-guides/schema/reserved-terms

This document contains a list of reserved terms, organized by category. Attempting to use these terms will result in a warning, informing you that you must use a different word instead.

![Reserved term warning in the UI](/images/docs/user-guides/reserved-terms-errormessage.png)

## GraphQL type names

- int
- boolean
- date
- datetime
- enum
- float
- fragment
- input
- interface
- json
- mutation
- node
- query
- scalar
- string
- subscription
- union

## Reserved non system type names

- Color
- ColorInput
- Entity
- HEX
- Id
- Locale
- Location
- LocationInput
- RGBA
- RGBAHue
- RGBATransparency
- RichText
- RichTextAST
- ScheduledOperation
- ScheduledRelease
- Search
- Status
- User

## Reserved non system field names

- createdat
- createdby
- documentInStages
- history
- id
- locale
- localizations
- publish
- publishedat
- publishedby
- status
- updatedat
- updatedby
- versions


---
# Working with the slug field

Source: https://hygraph.com/docs/developer-guides/schema/slug-field

## Overview

A slug field is a field type used to create parts of a URL that identify a page with a human readable slug, which is both user & search engine friendly. The resulting slugs are concise and contain relevant keywords.

![Slug example](/images/docs/user-guides/slug-example.png)

Typically, a slug consists of lowercase letters, numbers, and hyphens, with spaces replaced by hyphens or simply removed.

## What you can do

You can configure an initial value for slugs using the slug field type. This field is of type `String` in your GraphQL schema but provides a powerful UI feature that comes in the form of automatic initial value generation.

You can configure the slug field to be generated from other field values in your model.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xvthjbt007w5l5c66qdw" caption="Slug - Adding a slug field" />

## Create a slug field

1. Navigate to the Schema builder and select the model you want to add a slug field to.
2. Select `Slug` from the **Add field** sidebar.
3. Add a `Display name`, which will autocomplete the `API ID`. You can optionally add a `Description`.
4. Under **Slug options**, specify whether this field should be lowercase, and enable whether you want this field to be generated from a template.
5. If you opted to generate from template, enter a template for your slug.
6. Configure any additional settings for the model. By default, the field will be set to unique, and a specific matching pattern will be provided.
7. Click `Add` to save.

## Slug templates

Each Slug field template can be generated using the **Available fields** outlined above the input. If your model has a `title`, or `name` field, you could specify the slug template as `{title}`, or `{name}` respectively.

## Using the slug field

When creating content, the slug field will be automatically generated from the template field you're using.

For example, if your slug field is based off a `title` field, when you start typing into the `title` field, it will also update the slug field.

You can override the slug field value by typing in the box. You can also "Regenerate" the value to fallback to the template you provided.


---
# Taxonomies

Source: https://hygraph.com/docs/developer-guides/schema/taxonomies

## Overview

A taxonomy is a group of terms arranged in a hierarchical structure. The primary purpose of a taxonomy is to classify and logically connect related content items using a more elaborate structure than [enumerations](/docs/developer-guides/schema/using-enumerations). This helps with content management and improves user experience with enhanced searchability.

<Alert theme="info">
Taxonomies are an enterprise feature. <Link href="https://hygraph.com/contact" target="_blank">Contact our sales team for access</Link>.

</Alert>

## How it works

1. The developer or the administrator defines the taxonomy in the schema using hierarchical tags.
    - Example: `Clothes → Men → Pants → Formal`
2. The developer or the administrator adds the taxonomy to a model.
3. While creating content based on the model, the content team classifies content using one of the predefined terms in the taxonomy.

## Benefits of taxonomies

- Your end users can find and filter content easily.
- Your content is well-organized and well-structured in your content management system.
- You can dynamically classify content for search, filtering, and personalization purposes. For example, a user could search for full-sleeve formal shirts or full-sleeve shirts. If the user is looking for a full-sleeve shirt, they would be shown both formal and casual shirts. Depending on the parent-child relationships you’ve set up, your options to dynamically classify content are limitless.

## Permissions

Here, are the permissions given to the default roles in Hygraph:

| Role                        | Permissions                                         |
|-----------------------------|-----------------------------------------------------|
| Admin                       | <ul><li>Create, read, update and delete a taxonomy. </li><li>Create, read, update and delete taxonomy nodes.</li></ul> |
| Developer                   | <ul><li>Create, read, and update a taxonomy. </li><li>Create, read, update and delete taxonomy nodes.</li></ul> |
| Editor                      | <ul><li>Read a taxonomy. </li><li>Create, read, and update taxonomy nodes.</li></ul>          |
| Contributor                 | <ul><li>Read a taxonomy. </li><li>Read taxonomy nodes.</li></ul>                              |

## Create a taxonomy

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdinb5ej3jd007vybggpiup3" caption="Create a taxonomy" />

1. Navigate to the **Schema** builder.
2. In the Schema list, click **+ Add** next to Taxonomies. Or, if you're adding a taxonomy for the first time in the project, click **Taxonomies**, and then click the **+ Add Taxonomy** button located at the center of the screen. The **New Taxonomy** screen is displayed.
3. Provide a **Display name**. This is the name of the taxonomy that is displayed in Hygraph. The **API ID** field is autogenerated as you enter the **Display name**, but you can edit this value. The API ID is used to access this taxonomy through the API.
4. Optionally, you can add a **Description**.
5. Click **Add Taxonomy**. Now, the **Nodes** tab is displayed. This tab displays the parent-child relationships defined in this taxonomy.
6. The `Display name` of the taxonomy is available as the root node name. To modify this, hover over the root node, click **...** (context menu), and then click **Rename node**.
7. To add a child node to the root node, hover over the root node, and click **Add child node**. Provide a name, and click **Add**. The `API ID` is autogenerated as you enter the name. This ID is used to access the taxonomy node through the API.
  - You cannot have duplicate node or API IDs in the same taxonomy.

Repeat this step to create multiple parent-child relationships between the different nodes.

## Add a taxonomy to a model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdio8diu510d07w0fmb4q4f7" caption="Add taxonomy to a model" />

1. Navigate to the **Schema** builder.
2. Select the model you wish to add the taxonomy to.
3. From the **Add fields** right sidebar, select the **Taxonomy** field.
4. Complete the `Display name` field. This autogenerates the `API ID` field, but you can edit this value if you want.
5. Use the `Taxonomy` dropdown to select the taxonomy you want to add to this model.
6. Optionally, you can also add a `Description`.
7. This screen allows you to control different properties of your **Taxonomy** field: you can allow multiple values by selecting the checkbox under the `Field options` section.
8. Click `Add` to save.

After you add a taxonomy to your model, it is available for use in the Content Editor.

## Use demo taxonomy

1. Navigate to the **Schema** builder.
2. If you're adding a taxonomy for the first time in the project, click **Taxonomies**, and then click the **Add demo taxonomy** button located at the center of the screen.
3. The system generates the demo taxonomy and displays the taxonomy nodes.

## Modify a taxonomy

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdit5yj0atyz07vyad07cprq" caption="Modify a taxonomy" />

1. Navigate to the **Schema** builder.
2. Under **Taxonomies**, select the taxonomy that you want to modify.
3. On the **Nodes** tab, you can do the following:

    | Task                      | How to do it                         |
    |-----------------------------|------------------------------|
    | Add a child node            | Click **Add child node** next to the node. |
    | Edit name of existing node  | Click <img src="/images/docs/developer-guides/edit.png" class ="inline"></img> to update the name of the node.  |
    | Move node to a new parent   | Click <img src="/images/docs/developer-guides/move.png" class ="inline"></img> and select a new parent from the list of existing nodes.  |
    | Delete the node             | Click <img src="/images/docs/developer-guides/delete.png" class ="inline"></img> to delete the node. You cannot delete a taxonomy node, if it is used in a content entry. |

4. On the **Settings** tab, you can modify the display name and the API ID of the taxonomy, and add or update the description, if needed.

## Delete a taxonomy

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdixo0ywggbo07w0wommbob0" caption="Delete a taxonomy" />

1. Navigate to the **Schema** builder.
2. Select the taxonomy you want to delete.
3. Click **...** (context menu), and then **Delete** to delete the taxonomy.

## Related docs

- [Best practices for taxonomies](/docs/developer-guides/schema/taxonomies-best-practices) - Recommended strategies for designing and maintaining taxonomies.
- [API reference for taxonomies](/docs/api-reference/schema/taxonomies) - API reference document on fetching taxonomy and taxonomy nodes.
- [Filter taxonomies using the Content API](/docs/api-reference/content-api/filtering#taxonomy) - How to filter taxonomies using the Content API.
- [Filter taxonomies in the content table](/docs/editor-guides/content/filter-content#taxonomy) - How to filter entries by taxonomies in the content table.


---
# Best practices for taxonomies

Source: https://hygraph.com/docs/developer-guides/schema/taxonomies-best-practices

Taxonomies are hierarchical, centrally managed vocabularies that classify content across multiple models. Taxonomies include consistent labels that improve findability, search and filter UX, personalization, and governance.

## When to use taxonomies

Use taxonomies when you need:

- A shared classification system reused across multiple models, such as a Blog, Product, Case study, Event
- A hierarchy of terms. We recommend 3 nesting levels. Example: `Root → Category → Subcategory → Topic`
    - Hygraph supports up to 6 nesting levels, not counting the root.
- Consistent editorial language when terms change rarely.
- Filters in apps and custom views.

Currently, you cannot localize taxonomy fields in Hygraph. For locale‑specific category trees that diverge per language, you have two options:
  - **Same structure, but different labels:** Keep one taxonomy, and map term IDs to localized labels in your app or a helper model.
  - **Different structures per locale:** Create separate taxonomies, such as `Category_EN`, `Category_DE`, or use a localized Category model with references.

## When not to use taxonomies

We recommend that you do not use taxonomies in the following scenarios:

| Need	| Use	|
|-------|-----|
| Entity with fields or metadata on the nodes. Model lifecycle, validation, and localization may apply. For example, you want additional information such as logos, descriptions, links, country codes, SEO, and so on.  |	Model and reference |
| The values are per‑entry, ad‑hoc, or dynamic. For status, type, or flags, a small, closed, dynamic set of values is useful. |	Enumeration	|
| Navigation or menus that need ordering, audience rules, or content per node, compose into models. Optionally, mirror high‑level menu groups in a taxonomy only if you need to use filters.	| Model and component |
| Complex relationships or additional business logic. For example, creating a Compatibility taxonomy with nodes for each product and tagging Product A with Product B implies "A is compatible with B". This duplicates your products inside the taxonomy and does not let you capture details like "since version 2.0", "only in Europe", or "one-way vs. two-way compatibility". |	References (possibly with a join model) |

## Decision flowchart

![Taxonomy decision flowchart](/images/docs/developer-guides/taxonomy-decision-flowchart.png)

Create a taxonomy only if your answer is `YES` to the following questions:

1. Will the labels be **reusable**? Is this a vocabulary that should be centrally managed? Taxonomies are especially useful if reused across models, but even within a single model, they’re the right choice when you need a hierarchy rather than an enumeration.
2. Do the labels need to be **hierarchical**? Do we benefit from parent-child grouping?
3. Will the labels be **stable**?

If you answered No to any question, consider the following modeling options:

- No to Question 1 → **Enumeration** or **model-specific field**
- No to Question 2 → **Enumeration** or a **flat reference model**
- No to Question 3 → **Enumeration** or **string**

## Taxonomy patterns

A high-level overview of the taxonomy patterns:
- Up to three nesting levels (excluding the root) – Recommended for most use cases.
- Four to five nesting levels - Use only when following external standards or justified by customer requirements.

If your taxonomy goes deeper without clear justification, you are possibly introducing other dimensions, such as audience, format, or region. Rather than extending a single hierarchy, you can model these as enumerations, additional taxonomies, or references.

### Flat taxonomy

A flat taxonomy, `Root → Child`,  means everything sits one level below the root. This is possible, but it works like a long enumeration. Use this option only when you know you will expand this into a hierarchy later. Avoid placing a large number of siblings directly under the root, as this significantly reduces editor usability.

### Two-level taxonomy

A two-level taxonomy, `Root → Parent → Child`, is the most common structure. Example:  `Root → Industry → Sub-industry` or `Root → Category → Subcategory`. This approach provides editors with a clear structure while avoiding unnecessary complexity, and it enables effective filtering for end users.

### Three-level taxonomy

A three-level taxonomy, `Root → Level 1 → Level 2 → Level 3`, works well for complex content sets. It provides enough depth and remains manageable.

### Four-level and deeper taxonomy

A four+ level taxonomy (Root → up to Level 6) is valid in industries with established classification standards, such as the <Link href="https://en.wikipedia.org/wiki/Global_Industry_Classification_Standard" target="_blank">Global Industry Classification Standard</Link>. Hygraph supports up to 6 nesting levels, without counting the root. Such taxonomies are very powerful, but there could be complexity due to governance. Merges, splits, and reclassifications become heavy operations.

## Implementation tips in Hygraph

Begin with a simple taxonomy, then iterate based on usage data. Avoid over-engineering.

- Assign an owner per taxonomy. Restrict who can create or rename nodes in production, and ensure that significant changes to the taxonomy go through a proper review. By default, editors can create taxonomy nodes. You can use custom roles if you want to limit who can create taxonomy nodes.
- Set up a naming convention for the taxonomy nodes:
    - Display name - This is the node name that editors see. Keep it concise, and preferably use sentence case.
    - API ID - This is used to query the taxonomy and its nodes. Ensure that it is stable, machine-safe. Avoid renaming this later.
- Keep taxonomy depth less than or equal to three nodes.
- Add, deprecate, and remap nodes versus deleting them. Deleting nodes that are in use is disruptive.
- [Allow multiple taxonomy values](/docs/api-reference/schema/field-configuration#allow-multiple-values) in models only if required.
- Build out taxonomies in a testing environment. Use the testing environment to manage breaking changes. Use change logs or [schema as code](/docs/api-reference/schema/schema-as-code) to maintain previous versions.
- Keep trees separate for different purposes in larger projects.






---
# Using enumerations

Source: https://hygraph.com/docs/developer-guides/schema/using-enumerations

## Overview

An enumeration is a predefined set of values that represents a list of possible options.

<Alert theme="info" title="Are you looking for our API Reference?">

[Check out our API Reference document on enumerations](/docs/api-reference/schema/enumerations)

</Alert>

## What you can do

- You can use enumerations to group values within a type.

- You can use enumerations to create a list of values and add it to a model. The values can then be selected from a dropdown menu in the content creation screen.

## Create an enumeration

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xuhjhv2h07vxcvh0mh61" caption="Create an enumeration" />

1. Navigate to the **Schema** builder
2. You can create an enumeration by navigating to the Schema builder, locating enumerations on the Schema list, and then clicking on `+ Add` next to Enumerations on the Schema list, or the `+ Add Enumerations` button located at the center of the screen. The **New enumeration** screen will display as a result.
3. Complete the `Display name` field with the name that will be displayed in Hygraph. The `API ID` field will be autocompleted when you complete the `Display name`, but you can edit this value. The API ID is the ID for accessing this enumeration through the API.
4. Optionally, you can add a `Description`.
5. Under enumeration values, you can add a list of values by manually entering the `Display name`, which autocompletes the `API ID` field, and then clicking `+ Add`. Your values will display on a list below.
6. Once you have added all the enumeration values, click `Add Enumeration` at the bottom of the screen to finish the process.

## Use demo enumeration

![Create an enumeration](/images/docs/user-guides/enumerations/enumerations-use-demo.png)

1. Navigate to the **Schema** builder.
2. Click on `Add demo enumeration`, located at the center of the screen. 
3. The system will generate the demo enumeration and show you the enumeration details screen.

## Delete an enumeration

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xujzjbpv07w5uj3lj2s1" caption="Delete an enumeration" />

1. Navigate to the **Schema** builder.
2. Click on the enumeration you want to delete.
3. Click on the context menu to display the `Delete` option, then click on it to delete the enumeration.

## Add an enumeration to a model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xb59hu9r07vx7be3hlc6" caption="Add an enumeration to a model" />

1. Navigate to the **Schema** builder.
2. Click on the model you wish to add the enumeration to.
3. Select the **Enumeration** field from the **Add fields** right sidebar.
4. Complete the `Display name` field. This will autocomplete the `API ID` field, but you can edit this value if you want.
5. Use the `Enumeration` dropdown to select the enumeration you want to add to this model.
6. Optionally, you can also add a `Description`.
7. This screen allows you to control different properties of your **Enumeration** field: you can allow multiple values, localize the field, or use it as title field, by selecting the checkboxes under the `Field options` section of the screen.
8. Click `Add` to save.

After an enumeration has been configured for your model, you will be able to use it in the content editor.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xulyjbq407w5cqk2ntdg" caption="Use an enumeration in a content entry" />


---
# Variants

Source: https://hygraph.com/docs/developer-guides/schema/variants

Today, users expect personalized content tailored to their preferences. Generic content is less effective because users prefer relevant content that appeals to them. With the introduction of Variants, Hygraph empowers content teams to deliver tailored content experiences that resonate with specific user Segments. This level of personalization not only enhances user engagement but also drives conversion rates.

## Key terms

**Segments** - A named reference used to target a group of users based on shared characteristics or behaviors. The actual user lists for these groups are defined and managed in an external system. You use Segments to deliver specific content, that is, Variants to these external user groups. Examples of shared characteristics for segmentation are:
- Demographics: Age, gender, location, language
- Behavioral data: Pages visited, products viewed, time on site
- Engagement: Frequency of visits, previous purchases, email interactions

**Variants** - Personalized versions of content entries that are served depending on the defined Segment. Variants define what version of the content a Segment sees.

A main content entry can have many Variants, each tailored to a specific Segment. These Variants are not separate entries but linked to the main entry. They inherit structure or layout from the main entry while allowing customization of certain fields.

## Benefits

With Variants, you can create different pieces of content for different audiences. Here are a few benefits of Variants:

- Enables personalization and A/B testing use cases
- Provides support for targeted content without duplicating entries
- Helps manage multi-regional or multi-brand strategies efficiently

## Use cases

Hygraph doesn’t decide which content Variant is shown to your end-users, and we don’t collect or process any end-user data to drive Segment creation. While it is possible to build personalized experiences without an additional tool, we recommend using a personalization engine for more complex setups.

Here are a few use cases that Variants support:

- Show different homepage banners to users in Germany vs. the US.
- Highlight specific content to users based on their browsing history, or the platform they come from.
- Display metric units for Europe and imperial units for the US on a product page.
- Present different introductions or visuals depending on whether the reader is a developer or a marketer.

## Get started

**Prerequisites**

- You have already set up a content model.
- You have created at least one content entry based on the content model.

**Permissions**

Variants inherit permissions from their content model. So if a user can read, create, and update a model, they have the same permissions for Variants of entries based on the model.

**Limits**

- Variants are an enterprise feature. <Link href="https://hygraph.com/contact" target="_blank">Contact our sales team for access</Link>.
- You can create a maximum of 30 Variants per entry.
- Segments and Variants count toward the Content entries limits of your [billing plan](/docs/developer-guides/project/update-billing#commercial-limits).

**Steps**
1. [Enable Variant support for fields](#enable-variant-support-for-fields).
2. [(Optional) Modify your Segment system model](#optional-modify-your-segment-system-model).
2. [Add Segments](#add-a-segment).
3. [Add Variants for the main entry and link the Variant to one or more Segments](#add-a-variant-and-link-it-to-a-segment).

## Enable Variant support for fields

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdsuemx55pc807w3se7haa43" caption="Enable Variant support for fields" />

First, you need to enable Variant support on a per-field basis in your schema.

1. Go to the Schema Editor, and choose your content model.
2. On the **Fields** tab, click **Edit field** for the field that you want to add Variants.
    - Currently, Variants are not supported for custom fields. Our team is working on adding this functionality to the feature, and we’ll share new additions in future updates.
3. Under **Settings**, select the **Enable variants** check box.
    - You cannot enable Variant support for unique fields.
4. Click **Update**.

Repeat these steps for as many fields in the schema, as required.

If you disable Variant support for a field or delete a field that has Variant support enabled, the field and its associated content is removed from all Variants.

## (Optional) Modify your Segment system model

The Segment system model includes certain fields, by default. You can add more fields to the Segment model from the Field Types sidebar. Currently, Variants are not supported for custom fields. You cannot localize the fields of the Segment model.

## Add a Segment

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdq89l4v76xs07uv1nq28u9l" caption="Add a Segment" />

Next, add Segments to display content from different Variants.

1. In the Content Editor, under **Segments**, go to **All**.
2. Select **Add entry**.
3. Provide the name of the Segment and optionally, add a description.
4. Click **Save** or **Save & publish**.

Repeat the above steps to add multiple Segments.

## Add a Variant and link it to a Segment

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdq97wrs7rbx07uv6cac2c44" caption="Add a Variant and link it to a Segment" />

1. Go to the Content Editor, and open your content entry. This is the main content entry.
2. In the right sidebar, under **Variants**, select **Add**. A new version of the content entry is displayed. The values from the main entry for the default locale are copied into the Variant entry. This makes it easier to make adjustments, especially when the Variant only differs slightly from the main entry.
    - To add a new locale to the Variant, in the right sidebar, under **Localizations**, click the `+` icon next to the locale. The empty localized fields appear and you can enter the localized text for the Variant in these fields.
3. Only the fields that have Variant support enabled are available for editing. Make changes to the available fields, as required.
    - Turn on the **Show all fields** toggle to view the rest of the fields in the content model in read-only mode. If you want to edit the read-only fields, you need to go back to the content entry.
4. Now, click **Select segment**.
5. Choose one or more Segments that this Variant applies, and click **Add selected entries**.
6. Click **Save** or **Save & publish**.

<Alert theme="info">

You need to publish the Segment to the same stage as the Variants to see Variants of a certain Segment.

</Alert>

## Modify a Variant

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdqba4k793gq07uvaow9owm5" caption="Modify a Variant" />

After you save a Variant, you can modify the values in different fields of the Variant. You can also modify the Segments that you linked to this Variant.
  - Link more Segments - Select the Segment that you added, and click **Add segment**.
  - Unlink a Segment - Hover over the context menu next to a Segment, and click **Remove**.

## Behavior of Variant fields

Each variant maintains its own values independently. If the same content is needed across entries, you need to manually update it in each entry. When working with variant fields, note the following points:
- Main entry updates: Updating a variant-enabled field in the main entry does not update the same field in its variants.
- Variant Entry updates: Changes made to variant fields do not affect the corresponding fields in the main entry.

Publishing the main entry doesn’t auto-publish its variants. You need to publish each variant separately. To be able to publish a variant, you must have already published the main entry.

## Next steps

[Use Hygraph's Variants to achieve personalization in your setup](/docs/recipes/personalization/personalization-variants), whether you are just starting out or already have a personalization engine or a Customer Data Platform (CDP) in your setup.

You need to identify user Segments in real time, and then dynamically deliver content based on the Variants that you set up in Hygraph.

## Related docs

- [API reference for Variants](/docs/api-reference/schema/variants) - API reference document on fetching Variants and Segments.
- [Set up live preview for Variants](/docs/developer-guides/schema/live-preview#add-a-variants-preview-url) - Learn how to set up live preview for you Variants after you've set up a preview for your main content entry.
- [Achieve Personalization with Hygraph's Variants](/docs/recipes/personalization/personalization-variants) - Learn how to combine variants and segments to create personalized content experiences.
- [Set up personalization with Hygraph's Variants and frontend logic](/docs/recipes/personalization/personalization-example-variants-frontend-logic) - Practical guide to implement variant-based personalization in your frontend application.
- [Create Variants of content entries](/docs/editor-guides/content/create-variants) - As an editor, learn how to create and edit variants from the main content entry.


---
# Visual editing

Source: https://hygraph.com/docs/developer-guides/schema/visual-editing-overview

Visual editing lets editors review and change content directly from the frontend, without navigating the schema to find the right field. As a developer, you configure it once, and then editors can work from the preview. Hygraph provides two tools for this:
- Live preview
- Click to Edit

Both tools use the same Preview widget. You configure it once for each modelin the Schema builder. After that, live preview works immediately. Click to Edit requires additional SDK setup.

|                                      | Live preview | Click to Edit     |
|--------------------------------------|--------------|-------------------|
| Requires Preview widget              | Yes          | Yes               |
| Requires Preview SDK                 | No           | Yes               |
| Requires data attributes on frontend | No           | Yes               |
| Editors see content in context       | Yes          | Yes               |
| Editors can jump to a specific field | No           | Yes               |
| Locale switcher in preview panel     | Optional     | Optional          |
| Works outside Studio (standalone)    | No           | Yes               |
| Real-time updates while typing       | No           | (Optional) Yes    |

## Live preview

Live preview loads your frontend in a side-by-side iframe inside Studio. Editors open an entry, click **Open live preview**, and see exactly how their draft content looks alongside the entry form. When they save, the preview refreshes.

![Live preview](/images/docs/developer-guides/visual-editing-live-preview.png)

For live preview to work, you need to add a Preview widget to the model in the Hygraph schema and configure a preview URL that serves your content from the `DRAFT` stage.

If your project uses multiple locales, adding `{locale}` to the preview URL template activates a locale switcher in the preview panel. Editors can switch between locales directly in the preview without leaving Studio.

Start here if you want editors to see content in context before going further. Live preview has no SDK dependency and no frontend instrumentation. It is the fastest path to a working preview.

For more information, see [Live preview setup](/docs/developer-guides/schema/live-preview).


## Click to Edit

With Click to Edit, editors hover over any tagged element in the preview and click **Edit** to jump directly to that field in Studio. No manual navigation is required.

![Click to Edit](/images/docs/developer-guides/visual-editing-click-to-edit.png)

For Click to Edit to work, you need to install the <Link href="https://github.com/hygraph/preview-sdk" target="_blank">Hygraph Preview SDK</Link> in your frontend and add `data-hygraph-*` attributes to the elements you want to make editable. You instrument the fields that matter, and not everything on the page.

Start here if live preview is already working and editors are still spending time navigating to fields in the entry form. Click to Edit is an additive step, not a replacement for live preview setup.

See [Click to Edit setup](/docs/developer-guides/schema/click-to-edit) and the [Next.js App Router implementation](/docs/developer-guides/schema/click-to-edit-next-js-app-router) and [Next.js Pages Router implementation](/docs/developer-guides/schema/click-to-edit-next-js-pages-router).

## Where to begin

If you have not set up either tool yet, follow this order:

1. [Live preview](/docs/developer-guides/schema/live-preview): Add the Preview widget to your model, define your preview URL template, and configure your frontend to serve `DRAFT` content.
2. [Click to Edit](/docs/developer-guides/schema/click-to-edit): Install the Preview SDK and add data attributes to your frontend elements.
    - [Next.js App Router](/docs/developer-guides/schema/click-to-edit-next-js-app-router): Framework-specific implementation for Next.js App Router with code examples for simple fields and components.
    - [Next.js Pages Router](/docs/developer-guides/schema/click-to-edit-next-js-pages-router): Framework-specific implementation for Next.js Pages Router with code examples for simple fields and components.


---
# Deploy your Gatsby Cloud project with Hygraph webhooks

Source: https://hygraph.com/docs/developer-guides/webhooks/deploy-gatsby-project

<Alert theme="warning">

The Gatsby integration has been deprecated and no longer receives support. Please migrate to using webhooks by following the steps shown <a href="/docs/developer-guides/webhooks/deploy-gatsby-project#migrate-from-gatsby-integration-to-webhooks">Here</a> .

</Alert>

If you are using **Gatsby Cloud** for your deployments, you can use **Hygraph webhooks** to automatically deploy when content changes.

## Prerequisites

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a **Hygraph** project. Read [this](/docs/getting-started/fundamentals/quickstart#create-a-project) document to access further information on how to create Hygraph projects.
- You must have an **Gatsby Cloud** account. If you don't have one, you can create one <Link href="https://www.gatsbyjs.com/dashboard/signup" target="_blank">here</Link>.
- You must have a **Gatsby Cloud** site. Read <Link href="https://www.gatsbyjs.com/docs/quick-start/" target="_blank">this</Link> document to access further information on how to get started with Gatsby Cloud.

<Alert theme="warning">

**Webhooks are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Your Gatsby Cloud site

You can use your pre-existing Hygraph powered Gatsby site in Gatsby Cloud - if you have one - or you can create a new site by importing your pre-existing Gatsby project from a GitHub repository. You can follow <Link href="https://www.gatsbyjs.com/docs/sourcing-from-graphcms/#headless-the-graphcms-way" target="_blank">this guide</Link> for instructions on how to do this.

During the setup process, you will be asked to provide the necessary environment variables for your Gatsby site to build:

![Environment variables in Gatsby Cloud](/images/docs/user-guides/webhooks/gatsby/gatsby-environment-variables.png)

You will find this information in your Hygraph project by navigating to **Project settings > API access**.

| In Hygraph            | In Gatsby Cloud  |
| --------------------- | ---------------- |
| Content API           | HYGRAPH_ENDPOINT |
| Permanent Auth Tokens | HYGRAPH_TOKEN    |

You will find the **Content API** URL under **Endpoints**. Scroll down to the bottom of the screen to find the **Permanent Auth Tokens**.

<Alert theme="info">

You can follow the same process for <b>Build variables</b> and <b>Preview variables</b> in Gatsby Cloud.

</Alert>

## Configure webhooks

The first thing you need to do is navigate to your Gatsby Site, go to **Settings > Webhook**, and copy your **Builds Webhook**. Follow these steps afterwards:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/CPhJj5CRGWJ6cg2MePza" caption="Configure a webhook for your Gatsby Cloud site" />

1. In Your Hygraph Project, navigate to **Project Settings > Automation > Webhooks** in your Hygraph project, and click `Add webhook`.
2. The `Add webhook` screen will display. Complete the following information:
   - **Name:** Name for your webhook.
   - **Description:** Description for your webhook. Optional field.
   - **Include payload:** Switch. True by default. If true, data will be sent via the webhook.
   - **Method:** Dropdown menu that allows you to select an HTTP method from a list. The default value is **POST**, but you can also select **DELETE**, **GET** or **PUT**.
   - **URL:** Webhook URL. This is where you paste the **Builds Webhook** that you copied from your Gatsby Site settings.
   - **Secret key:** You can optionally add a secret key to sign the payload of your webhook. The secret key allows the other end to check that the source is genuine. This can be used to verify requests and, for instance, avoid triggering deploys from unknown sources.
   - **Triggers:** This is where you select which Models, Stages, Actions and Sources should trigger your webhook. Each item has a dropdown menu, where you can select one or more options. Selecting none acts as a wildcard, then all models will trigger the webhook. If you're a developer, [this document](/docs/api-reference/basics/webhooks#triggers) contains some more information on triggers that might be useful to you.
   - **Headers:** Here you can configure your headers by adding additional **Key** and **Value** data, then clicking on the `Add` button. You can add multiple **key-value** sets, and you can delete the ones you added by clicking on the trash icon. Some endpoints require authentication using API Keys, which could be set here.

![Gatsby webhook example - Headers](/images/docs/user-guides/webhooks/gatsby/gatsby-keyvalue.png)

<Alert theme="warning">

Follow the same process to create a second webhook using the <b>Preview webhook</b> from your Gatsby cloud site if you want to create a preview link as well.

</Alert>

## Trigger a Gatsby Cloud build from Hygraph

Once the webhook has been [configured](/docs/developer-guides/webhooks/deploy-gatsby-project#configure-webhooks), performing one of the trigger actions will trigger a build in Gatsby Cloud.

For instance, if the trigger actions you configured for the webhook are `PUBLISH` and `UNPUBLISH`, doing either of those actions in the **Content editor** will trigger a new build in Gatsby Cloud.

You will be able to check the new build in your **Hygraph project** by checking the [logs](/docs/api-reference/basics/webhooks#webhook-logs). You can also see this in your in your **Gatsby Site**, under **Master > Build history**.

## Migrate from Gatsby integration to webhooks

Follow these steps to migrate from your Gatsby integration to webhooks:

1. In your **Hygraph** project, navigate to **Apps** and locate your Gatsby integration card.
2. Click on the trash icon to delete.
3. Finally, navigate to Webhooks and follow the [configuration process](/docs/developer-guides/webhooks/deploy-gatsby-project#configure-webhooks).

## Resources

- <Link href="https://www.gatsbyjs.com/docs/" target="_blank">Gatsby Cloud documentation</Link>


---
# Deploy your Vercel project with Hygraph webhooks

Source: https://hygraph.com/docs/developer-guides/webhooks/trigger-static-build

If you are using Vercel for your deployments, you should check our official integration for a one-click build button. Alternatively, if you want a hands off approach, you can use Hygraph webhooks to automatically deploy when content changes.

<Alert theme="warning">

**Webhooks are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## 1. Create your deploy hook

Inside your Vercel project Git settings, scroll to the "Deploy Hooks" section. You'll want to specify the name of your hook, and the Git branch name you want to trigger a deployment for.

The name is only a reference to you, and you should never share these deployment URLs, as they're public, and don't require any authentication to call.

![Vercel Deploy Hooks form](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/C9OgYS2RR5myXEplaiwP)

Once you've configured your hook, create it, and copy the URL.

![Deploy published content on master](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/6XdFUbySlyhtODVugKoV)

## 2. Configure Hygraph

Now navigate to **Project Settings > Automation > Webhooks** in your Hygraph project, and click `Add webhook`.

Give your webhook a name, and paste your Vercel deploy hook URL inside the `URL` input. You can disable including the payload.
![Hygraph webhook config](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/XCUte3ONRAK6uAOFX9LN)

Next you will want to configure the triggers which call the Vercel deploy hook. You can specify:

**Content Model**

You can specify one or more content models within your project that causes this webhook to trigger. If you don't specify any, then any content model will be linked to this webhook.

**Stage**

In some cases you may want to deploy a custom content stage such as DRAFT to a staging environment. When you need to do this, you'll most likely want to duplicate your project inside Vercel, connected to the same repo, and repeat step 1.

In this example, we'll select `Published` as the stage we're watching for content to be published to. This means if someone is drafting a post inside Hygraph, then our Vercel deploy hook will not be called.

**Action**

You can specify one or more actions to watch to trigger your Vercel build hook. In this example, we want to redeploy our Vercel project whenever content is published, or unpublished, so we'll opt to leave this field empty.

![Hygraph webhook triggers](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/1Pe63XUTMK313DHd4XL8)

## 3. Publish content and deploy

Now head to your content editor, make a change, and click "Save and publish". You'll then notice inside your Vercel deployments list there is a new build.

![Save and publish button](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/8DWEiZH4TUGyHMQ8mcXO)

That's it!


---
# Webhooks overview

Source: https://hygraph.com/docs/developer-guides/webhooks/webhooks-overview

## Overview

This document shares general information about the use of webhooks with Hygraph, such as configuring webhooks, viewing logs, and editing or deleting webhooks.

<Alert theme="warning">
For specific information about the use of webhooks with external apps, please access the corresponding guide using the left side navigation menu.
</Alert>

<Alert theme="info" title="Are you looking for our API Reference?">
[Check out our API Reference document on webhooks](/docs/api-reference/basics/webhooks)
</Alert>

## Configure webhooks

To configure webhooks, follow these steps:

![Add a webhook](/images/docs/user-guides/webhooks/webhooks-create.png)

1. In your project, navigate to **Project Settings > Automation > Webhooks**.
2. Click `Add webhook`.
3. The `Add webhook` screen will display. Complete the following information:
   - **Name:** Name for your webhook.
   - **Description:** Description for your webhook. Optional field.
   - **Include payload:** Select this checkbox to allow applications to send and receive data packets.
   - **Method:** Dropdown menu that allows you to select an HTTP method from a list. You can select **POST**, **DELETE**, **GET** or **PUT**.
   - **URL:** Webhook URL. This is information that you will get from the connected app. Please check the corresponding guide for specific information about this.
   - **Secret key:** You can optionally add a secret key to sign the payload of your webhook. The secret key allows the other end to check that the source is genuine. You can use this to verify requests and, for instance, avoid triggering deploys from unknown sources.
   - **Triggers:** This is where you select which **Models**, **Stages**, **Actions** and **Sources** should trigger your webhook. Each item has a dropdown menu, where you can select one or more options. Selecting none acts as a wildcard, then all models will trigger the webhook. [This document](/docs/api-reference/basics/webhooks#triggers) contains some more information on triggers.
   - **Headers:** Here you can configure your headers by adding additional **Key** and **Value** data, then clicking `+ Add`. You can add multiple **key-value** sets, and you can delete the ones you added by selecting the `Remove` option in the context menu. Some endpoints require authentication using API Keys, which could be set here.
     ![Webhook headers](/images/docs/user-guides/webhooks/webhooks-keyvalue.png)

## View webhook logs

1. In your project, navigate to **Project Settings > Automation > Webhooks**.
2. Click **View logs** next to the webhook for which you want to check logs.

The logs screen will display as a result. This screen allows you to monitor the recent activity of your webhook from the last 7 days.

**Clicking on a log item displays its details:**

![Webhook logs](/images/docs/user-guides/webhooks/log-details.png)

## Disable or enable a webhook

![Webhook status](/images/docs/user-guides/webhooks/webhooks-status.png)

You can see whether a webhook is set to `Active` or `Inactive` next to its name on the webhook card.

![Disable a webhook](/images/docs/user-guides/webhooks/webhooks-disable.png)

To disable or enable a webhook, use the context menu and select `Pause` / `Resume`.

## Edit or delete a webhook

![Webhook - Edit and delete icons](/images/docs/user-guides/webhooks/edit-delete-webhooks.png)

Click on the context menu and select `Delete` to delete the webhook, or on `Edit` to edit its details. You can learn more about each of the fields you can edit [here](/docs/developer-guides/webhooks/webhooks-overview#configure-webhooks).


---
# Migration to Hygraph Asset Management System

Source: https://hygraph.com/docs/api-reference/assets/asset-migration

## Overview

<Alert theme="warning" title="Migrate to the Hygraph Asset Management System">

- The new asset system migration tooling is only be available for Hygraph Studio.
- We will automatically migrate free projects that have not migrated by the **end of April, 2025**.
- Paid & Enterprise projects have an extended migration timeline until **end of May, 2025**.

</Alert>

At the moment, Hygraph projects can use one of two asset systems. Projects created after February 2024 will use the new **Hygraph Asset Management** system, while older projects will use the **Legacy asset system**.

This document discusses the differences between both systems and the migration flows available.

If your project uses the old asset system and needs to migrate to the new one, the UI will show you that an action is required:

![Asset migration - action required](/images/docs/api-reference/assets/asset-migration-required.png)

When you go to **Project Settings > Environments**, you will see this.

![Asset migration - action required](/images/docs/api-reference/assets/migration-required.png)

<Alert theme="info" title="Please note">

- **Paid projects** can create a [test environment for asset migration](/docs/api-reference/assets/asset-migration#migration-environment), but **free projects** can't. 

- **All projects** can migrate the master environment and others ["in-place"](/docs/api-reference/assets/asset-migration#in-place-migration), turning them into read-only during migration. They can do this one environment at a time.

</Alert>

## Changes

The systems differ in four important areas. This section shows you a comparative view of these differences.

### Asset URL

The URL the new Hygraph Asset Management system uses to deliver assets slightly differs from the Legacy system.

Instead of the [`media.graphassets.com`](http://media.graphassets.com) URL that the Legacy Asset System uses, the new URL uses a regional subdomain and so it looks like this: [`regionalSubdomain.graphassets.com`](http://regionalSubdomain.graphassets.com). 

For example, if your project is hosted in our shared Germany (Frankfurt) region, the domain will be [`eu-central-1-shared-euc1-02.graphassets.com`](http://eu-central-1-shared-euc1-02.graphassets.com/).

Additionally, the old asset URL only contains a unique handle and some additional transformations following this format:

```json
media.graphassets.com/<transformations>/handle
```

The new Hygraph Asset Management system URL includes an additional environment identifier and an optional filename at the end:

```json
<regional-subdomain>.graphassets.com/<environmentId>/<transformations>/handle/filename.jpg
```

<Alert theme="info" title="Pro Tip">

The optional filename at the end of the URL needs to match the filename used to upload the asset. 

The file extension (`jpg`, `webp`, etc.) needs to match the current version of the asset. If you convert a `jpg` to `webp` using URL transformations, that extension at the end needs to be `webp`.

</Alert>

#### environmentId

With the Hygraph Asset Management System, the asset URL includes the identifier `environmentId`, like so:

```json
<regional-subdomain>.graphassets.com/<environmentId>/<transformations>/handle/filename.jpg
```

This `environmentId` is the asset config `apikey` from a specific environment.

You can easily get this ID in the API Playground, from the management API:

```graphql
{
  viewer {
    project(id: "...") {
      environment(name: "master") {
        assetConfig {
          apiKey #<-- this is the "envID"
        }
      }
    }
  }
}
```

Select the `Management API` in the API Playground to get this information. To do this, use the menu at the top-left of the API Playground, like so:

![Management API in the API Playground](/images/docs/api-reference/assets/management-api-in-playground.png)

#### Next.js

For Next.js you will need a new configuration for the asset domain. Since the images are in the Hygraph CDN, you need to specify our domain in the `next.config.js` file. For more information, <Link href="https://nextjs.org/docs/app/api-reference/components/image#remotepatterns" target="_blank">check this guide</Link>.

```js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.graphassets.com',
      },
    ],
  },
};
```

#### Astro

For Astro you will need a new configuration for the asset domain. Since the images are in the Hygraph CDN, you need to specify our domain in the `astro.config.mjs` file:

```js
export default defineConfig({
  // ... Rest of the configuration
  image: {
    domains: ["https://**.graphassets.com"],
  },
});
```

### Transformations

The Legacy Asset system natively supported the URL transformations `resize` and `output`. 

<Alert theme="info" title="Pro Tip">

If you were using other undocumented transformations, please reach out to us or check in the following information if the new system supports them.

</Alert>

The new Hygraph Asset Management system supports additional transformations:

- [resize](/docs/api-reference/assets/transformations#resize)
- [blur](/docs/api-reference/assets/transformations#blur)
- [border](/docs/api-reference/assets/transformations#border)
- [compress](/docs/api-reference/assets/transformations#compress)
- [crop](/docs/api-reference/assets/transformations#crop)
- [quality](/docs/api-reference/assets/transformations#quality)
- [sharpen](/docs/api-reference/assets/transformations#sharpen)
- [auto_image](/docs/api-reference/assets/transformations#auto-image)
- [output](/docs/api-reference/assets/transformations#file-type-conversion) (File type conversions)

<Alert theme="info" title="Pro Tip">

**File Conversions (output)**

At the moment, the Hygraph Asset Management system only supports transformations between image mime types. [Check out this table to learn about this in detail](/docs/api-reference/assets/transformations#file-type-conversion).

If you were using more advanced transformations, like `xls to pdf` or other unsupported ones, please reach out to us and let us know.

</Alert>

### Uploading Assets via API

While the Legacy Asset System used the Asset Upload API, with the new Hygraph Asset Management system asset uploads are a part of the native GraphQL API. You can still upload assets using a [remote URL](/docs/api-reference/assets/uploading-assets#upload-by-remote-url) or a [local file](/docs/api-reference/assets/uploading-assets#upload-by-file), though the process is slightly different.

Size limits for uploaded files depend on the plan. <Link href="https://hygraph.com/pricing" target="_blank">Check out our pricing page.</Link>

<Alert theme="info" title="Webhooks & asset uploads">

Make sure you read our [webhooks documentation](/docs/api-reference/basics/webhooks#webhooks-and-assets) to understand how they work with the Hygraph Asset Management System.

</Alert>

#### Upload by file

**Uploading a local file** is now a two-step process. You will need to first call a `createAsset` mutation passing some basic information about the asset, and then use the returned information to send the actual file via a pre-signed URL. 

<Alert theme="info" title="Pro Tip">

[Our documentation explains this process in detail](/docs/api-reference/assets/uploading-assets#upload-by-file).

</Alert>

#### Upload by remote URL

The **Upload assets by remote URL** method lets you upload assets in the GraphQL API by passing the URL of an asset hosted somewhere publicly accessible in the `createAsset` mutation.

Here's an example for you:

```graphql
mutation test {
  createAsset(
    data: {
			uploadUrl:"https://images.unsplash.com/photo-1682687218147-9806132dc697"
    }
  ) {
    id
    url
  }
}
```

### Upload Status

The new Hygraph Asset Management System handles the uploading process asynchronously, and so asset entries now have an **upload status**. 

<Alert theme="warning">

This is mostly relevant when using **Upload by file**, but also applies to **uploading via remote URL**, except we handle the fetching of the remote asset directly.

</Alert>

When first calling the `createAsset` mutation, the asset entry is created in an `ASSET_CREATE_PENDING` status while we wait for the file to be sent to us via the pre-signed URL. After successfully receiving the file, the status switches to `ASSET_UPLOAD_COMPLETE`. If there is an error, it will switch to `ASSET_ERROR_UPLOAD` instead. 

<Alert theme="info" title="Webhooks & asset uploads">

Make sure you read our [webhooks documentation](/docs/api-reference/basics/webhooks#webhooks-and-assets) to understand how they work with the Hygraph Asset Management System.

</Alert>

If you do not send a file within the default time window, the asset entry stays in `ASSET_CREATE_PENDING` and might be cleaned up eventually. 

Be aware that all non-successful asset uploads are hidden by default on the API, but can be retrieved like this:

```graphql
{
  assets(where: {
    upload: {status_not_in: ASSET_UPLOAD_COMPLETE}
  }) {
    createdAt
    id
    publishedAt
    fileName
    url
    updatedAt
  }
}
```

### Upload Widget

The upload widget in the Hygraph UI is different depending on the asset system that your project uses.

Projects that use the new Hygraph Asset Management system can see a new upload widget within the webapp. For now, it only offers uploading a local file, but will soon be extended to also support uploading a remote URL. 

This is what it looks like at the moment:

![UI - Hygraph Asset Management system](/images/docs/api-reference/assets/hygraph-asset-management-system-ui.png)

Compared to this, the upload widget for the Legacy Asset system offers options to upload local files, upload using a remote URL, doing a web search, as well as using Facebook, Instagram and Google Drive:

![UI - Legacy Asset system](/images/docs/api-reference/assets/legacy-asset-system-ui.png)

<Alert theme="info">

If you'd like to see any of these options brought back or if you have additional suggestions, please let us know!

</Alert>

### Webhooks

If your project uses webhooks with the Hygraph Asset Management System, be aware that asset uploads are asynchronous. "Create" webhooks are triggered before uploads complete, causing potential issues if external systems expect assets to be available immediately.

The asset status starts as `ASSET_CREATE_PENDING` and switches to `ASSET_UPLOAD_COMPLETE` when ready.

Learn more about this process [here](/docs/api-reference/basics/webhooks#webhooks-and-assets).

## Migration environment

<Alert theme="warning">

**The new asset system migration tooling is only be available for Hygraph Studio.**

</Alert>

<Alert theme="info">

This option is only available for paid plans. Please [contact sales](/contact) for further information.

The resulting environment cannot be promoted to Master, but you can use it for testing purposes, to assess the impact of the migration and look into what additional actions you may need to take.

</Alert>

Every Hygraph project with a paid plan - Growth, Growth with add-ons, and Enterprise - will receive a free environment that allows you to clone your `master` environment using the new asset management system. 

To start the migration process using a test environment, go to `Project settings > General > Environments` and click `Configure migration`. 

Select `Clone Master environment with new asset system for testing` on the Asset migration popup.

![Migration environment](/images/docs/api-reference/assets/migration-environment.png)

Click `Start migration` to continue.

The newly created environment will be a one-to-one copy of your `master` environment with all your assets migrated to use the new system, including all the above mentioned changes.

The system assigns the new environment the name **Asset migration**, and a notification at the top of the screen informs you that the environment has been successfully migrated to the new asset system:

![Asset migration environment](/images/docs/api-reference/assets/asset-migration-environment-cloned.png)

In that migration environment, you can test how the new asset system behaves and if there are any breaking changes compared to your production environment.

[The comparison information](/docs/api-reference/assets/asset-migration#changes) in this document will help you spot potential issues. For instance, since we've explained that asset URLs change with the new system, you might want to look into where you are using those URLs that might need updating. 

<Alert theme="warning">

This migration environment can't be promoted to `master` and will be fully removed once the Legacy Asset System is deprecated. 

Please use it for testing purposes, before using our [in-place migration](/docs/api-reference/assets/asset-migration#in-place-migration) process. 

After cloning the migration environment, the `Clone Master environment with new asset system for testing` will no longer appear on the **Asset migration** popup

</Alert>

## In-place migration

<Alert theme="warning">

**The new asset system migration tooling is only be available for Hygraph Studio.**

</Alert>

The migration flow offers two options for in-place migration. You can migrate your Master environment or others you may have.

To start the migration process, go to `Project settings > General > Environments` and click `Configure migration`. 

On the **Asset migration** popup, select which environment you want to migrate to the new asset system:

![In-place migration options](/images/docs/api-reference/assets/asset-migration-options.png)

- `Migrate Master environment`: This option migrates your Master environment to the new asset system.
- `Migrate a specific environment other than master`: This option allows you to select other environments you may have. Please note that if you have more than one environment, you will eventually need to migrate all of them.

As this migration involves the risk of breaking changes, the system will prompt you to confirm that you have read our migration documentation:

![Asset migration warning](/images/docs/api-reference/assets/asset-migration-warning.png)

Click `Start migration` to continue. **Your environment will turn read-only for the duration of the migration process.**

During the migration process, the migration status displays on the left side of the screen:

![Migration in progress](/images/docs/api-reference/assets/asset-migration-callouts.png)

### Asset URLs in JSON fields

During the migration process, we go through every single `Markdown` and `Rich Text` field, and replace the old asset URL with the new one.

However, one field that could potentially store asset URLs as well is the `Single Line`, `Multiple Line`, and `JSON` field, but we don't automatically migrate them.

If your project uses these fields to store asset URLs, you will need to update them manually. To do so, you will need to go through all available content entries that use these fields, and check if they contain `media.graphassets.com`. If they do, you should manually replace that URL with the new one. This can also be done by using Content API filters.

## Migration & old URLs

Like we mentioned before, the new asset system uses slightly different URLs. Make sure to check for asset URLs stored in other places, such as source code or external systems.

<Alert theme="error" title="When will my old URLs stop working?">

We will sunset the old asset domain after the **end of June, 2025**.

</Alert>


---
# Assets API reference

Source: https://hygraph.com/docs/api-reference/assets/assets-overview

## Overview

The Asset model is included with every project, can be modified with custom [Field Types](/docs/api-reference/schema/field-types), and are [localized](/docs/api-reference/content-api/localization) by default, but cannot be deleted.

While most commonly used for photos, can support any file type including audio files, zip files, and more.

The Asset type extends the [system fields](/docs/api-reference/schema/system-fields).

Here are some links that might help you:

| Document name                                                       | Description                                                                       |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [Fetching assets](/docs/api-reference/assets/fetching-assets)       | Learn about the 4 query types that Hygraph automatically creates for every asset. |
| [Referencing assets](/docs/api-reference/assets/referencing-assets) | Learn how to query assets in relation to a model in your schema.                  |
| [Transformations](/docs/api-reference/assets/transformations)       | Learn about asset transformations.                                                |
| [Uploading assets](/docs/api-reference/assets/uploading-assets)     | Learn how to upload assets by file and by remote URL.                             |
| [Updating assets](/docs/api-reference/assets/updating-assets)       | Learn how to use the `updateAsset` mutation.                                      |
| [Deleting assets](/docs/api-reference/assets/deleting-assets)       | Learn how to delete assets using the `deleteAsset` mutation.                      |
| [Publishing assets](/docs/api-reference/assets/publishing-assets)   | Learn how to use the `publishAsset` and `unpublishAsset` mutations.               |
| [Localized assets](/docs/api-reference/assets/localized-assets)     | Learn about asset localization.                                                   |
| [Embedded types](/docs/api-reference/assets/embedded-types)         | Learn how to ember assets into Rich Text fields.                                  |

## Which asset system does my project use?

At the moment, Hygraph projects can use one of two asset systems. Projects created after February 2024 will use the new **Hygraph Asset Management** system, while projects that are older than that will use the **Legacy asset system**.

<Alert theme="warning">

If your project is a clone of an older project, it will use the legacy asset system.

</Alert>

To learn what system your project uses, check the asset upload popup in the UI.

![UI asset upload](/images/docs/api-reference/assets/ui-asset-upload.png)

If your project shows this, you are using the legacy asset system:

![UI - Legacy Asset system](/images/docs/api-reference/assets/legacy-asset-system-ui.png)

If your project shows this, you are using the Hygraph Asset Management system:

![UI - Hygraph Asset Management system](/images/docs/api-reference/assets/hygraph-asset-management-system-ui.png)

Another way to quickly see which asset system your project uses is to navigate to **Project Settings > Endpoints**, and look for the **Assets** section.

If you see this, your project uses the new Hygraph Asset Management system:

![Hygraph Asset Management system](/images/docs/api-reference/assets/hygraph-asset-management-system.png)

If you see this, your project uses the Legacy Asset system:

![Legacy Asset system](/images/docs/api-reference/assets/legacy-asset-system.png)

<Alert theme="info" title="Pro Tip">

While both systems are available, our documentation will provide information on how to work with each. You will find this in our API Reference for Assets in the [transformations](/docs/api-reference/assets/transformations), [asset upload](/docs/api-reference/assets/uploading-assets), and [localization](/docs/api-reference/assets/localized-assets) documents.

Simply identify the system your project uses and proceed with that documentation.

</Alert>

---
# Border transformation HEX values

Source: https://hygraph.com/docs/api-reference/assets/border-hex-values

This is a list of HEX values that you can use with the [`border` transformation](/docs/api-reference/assets/transformations#border) in Hygraph:

| Color name           | HEX value  |
| -------------------- | ---------- |
| aliceblue            | `F0F8FFFF` |
| antiquewhite         | `FAEBD7FF` |
| aqua                 | `00FFFFFF` |
| aquamarine           | `7FFFD4FF` |
| azure                | `F0FFFFFF` |
| beige                | `F5F5DCFF` |
| bisque               | `FFE4C4FF` |
| black                | `000000FF` |
| blanchedalmond       | `FFEBCDFF` |
| blue                 | `0000FFFF` |
| blueviolet           | `8A2BE2FF` |
| brown                | `A52A2AFF` |
| burlywood            | `DEB887FF` |
| cadetblue            | `5F9EA0FF` |
| chartreuse           | `7FFF00FF` |
| chocolate            | `D2691EFF` |
| coral                | `FF7F50FF` |
| cornflowerblue       | `6495EDFF` |
| cornsilk             | `FFF8DCFF` |
| crimson              | `DC143CFF` |
| cyan                 | `00FFFFFF` |
| darkblue             | `00008BFF` |
| darkcyan             | `008B8BFF` |
| darkgoldenrod        | `B8860BFF` |
| darkgray             | `A9A9A9FF` |
| darkgreen            | `006400FF` |
| darkgrey             | `A9A9A9FF` |
| darkkhaki            | `BDB76BFF` |
| darkmagenta          | `8B008BFF` |
| darkolivegreen       | `556B2FFF` |
| darkorange           | `FF8C00FF` |
| darkorchid           | `9932CCFF` |
| darkred              | `8B0000FF` |
| darksalmon           | `E9967AFF` |
| darkseagreen         | `8FBC8FFF` |
| darkslateblue        | `483D8BFF` |
| darkslategray        | `2F4F4FFF` |
| darkslategrey        | `2F4F4FFF` |
| darkturquoise        | `00CED1FF` |
| darkviolet           | `9400D3FF` |
| deeppink             | `FF1493FF` |
| deepskyblue          | `00BFFFFF` |
| dimgray              | `696969FF` |
| dimgrey              | `696969FF` |
| dodgerblue           | `1E90FFFF` |
| firebrick            | `B22222FF` |
| floralwhite          | `FFFAF0FF` |
| forestgreen          | `228B22FF` |
| fractal              | `808080FF` |
| fuchsia              | `FF00FFFF` |
| gainsboro            | `DCDCDCFF` |
| ghostwhite           | `F8F8FFFF` |
| gold                 | `FFD700FF` |
| goldenrod            | `DAA520FF` |
| gray0                | `000000FF` |
| gray1                | `030303FF` |
| gray2                | `050505FF` |
| gray3                | `080808FF` |
| gray4                | `0A0A0AFF` |
| gray5                | `0D0D0DFF` |
| gray6                | `0F0F0FFF` |
| gray7                | `121212FF` |
| gray8                | `141414FF` |
| gray9                | `171717FF` |
| gray10               | `1A1A1AFF` |
| gray11               | `1C1C1CFF` |
| gray12               | `1F1F1FFF` |
| gray13               | `212121FF` |
| gray14               | `242424FF` |
| gray15               | `262626FF` |
| gray16               | `292929FF` |
| gray17               | `2B2B2BFF` |
| gray18               | `2E2E2EFF` |
| gray19               | `303030FF` |
| gray20               | `333333FF` |
| gray21               | `363636FF` |
| gray22               | `383838FF` |
| gray23               | `3B3B3BFF` |
| gray24               | `3D3D3DFF` |
| gray25               | `404040FF` |
| gray26               | `424242FF` |
| gray27               | `454545FF` |
| gray28               | `474747FF` |
| gray29               | `4A4A4AFF` |
| gray30               | `4D4D4DFF` |
| gray31               | `4F4F4FFF` |
| gray32               | `525252FF` |
| gray33               | `545454FF` |
| gray34               | `575757FF` |
| gray35               | `595959FF` |
| gray36               | `5C5C5CFF` |
| gray37               | `5E5E5EFF` |
| gray38               | `616161FF` |
| gray39               | `636363FF` |
| gray40               | `666666FF` |
| gray41               | `696969FF` |
| gray42               | `6B6B6BFF` |
| gray43               | `6E6E6EFF` |
| gray44               | `707070FF` |
| gray45               | `737373FF` |
| gray46               | `757575FF` |
| gray47               | `787878FF` |
| gray48               | `7A7A7AFF` |
| gray49               | `7D7D7DFF` |
| gray50               | `7F7F7FFF` |
| gray51               | `828282FF` |
| gray52               | `858585FF` |
| gray53               | `878787FF` |
| gray54               | `8A8A8AFF` |
| gray55               | `8C8C8CFF` |
| gray56               | `8F8F8FFF` |
| gray57               | `919191FF` |
| gray58               | `949494FF` |
| gray59               | `969696FF` |
| gray60               | `999999FF` |
| gray61               | `9C9C9CFF` |
| gray62               | `9E9E9EFF` |
| gray63               | `A1A1A1FF` |
| gray64               | `A3A3A3FF` |
| gray65               | `A6A6A6FF` |
| gray66               | `A8A8A8FF` |
| gray67               | `ABABABFF` |
| gray68               | `ADADADFF` |
| gray69               | `B0B0B0FF` |
| gray70               | `B3B3B3FF` |
| gray71               | `B5B5B5FF` |
| gray72               | `B8B8B8FF` |
| gray73               | `BABABAFF` |
| gray74               | `BDBDBDFF` |
| gray75               | `BFBFBFFF` |
| gray76               | `C2C2C2FF` |
| gray77               | `C4C4C4FF` |
| gray78               | `C7C7C7FF` |
| gray79               | `C9C9C9FF` |
| gray80               | `CCCCCCFF` |
| gray81               | `CFCFCFFF` |
| gray82               | `D1D1D1FF` |
| gray83               | `D4D4D4FF` |
| gray84               | `D6D6D6FF` |
| gray85               | `D9D9D9FF` |
| gray86               | `DBDBDBFF` |
| gray87               | `DEDEDEFF` |
| gray88               | `E0E0E0FF` |
| gray89               | `E3E3E3FF` |
| gray90               | `E5E5E5FF` |
| gray91               | `E8E8E8FF` |
| gray92               | `EBEBEBFF` |
| gray93               | `EDEDEDFF` |
| gray94               | `F0F0F0FF` |
| gray95               | `F2F2F2FF` |
| gray96               | `F5F5F5FF` |
| gray97               | `F7F7F7FF` |
| gray98               | `FAFAFAFF` |
| gray99               | `FCFCFCFF` |
| gray100              | `FFFFFFFF` |
| gray                 | `7E7E7EFF` |
| green                | `008000FF` |
| greenyellow          | `ADFF2FFF` |
| grey                 | `808080FF` |
| honeydew             | `F0FFF0FF` |
| hotpink              | `FF69B4FF` |
| indianred            | `CD5C5CFF` |
| indigo               | `4B0082FF` |
| ivory                | `FFFFF0FF` |
| khaki                | `F0E68CFF` |
| lavender             | `E6E6FAFF` |
| lavenderblush        | `FFF0F5FF` |
| lawngreen            | `7CFC00FF` |
| lemonchiffon         | `FFFACDFF` |
| lightblue            | `ADD8E6FF` |
| lightcoral           | `F08080FF` |
| lightcyan            | `E0FFFFFF` |
| lightgoldenrodyellow | `FAFAD2FF` |
| lightgray            | `D3D3D3FF` |
| lightgreen           | `90EE90FF` |
| lightgrey            | `D3D3D3FF` |
| lightpink            | `FFB6C1FF` |
| lightsalmon          | `FFA07AFF` |
| lightseagreen        | `20B2AAFF` |
| lightskyblue         | `87CEFAFF` |
| lightslategray       | `778899FF` |
| lightslategrey       | `778899FF` |
| lightsteelblue       | `B0C4DEFF` |
| lightyellow          | `FFFFE0FF` |
| lime                 | `00FF00FF` |
| limegreen            | `32CD32FF` |
| linen                | `FAF0E6FF` |
| magenta              | `FF00FFFF` |
| maroon               | `800000FF` |
| mediumaquamarine     | `66CDAAFF` |
| mediumblue           | `0000CDFF` |
| mediumorchid         | `BA55D3FF` |
| mediumpurple         | `9370DBFF` |
| mediumseagreen       | `3CB371FF` |
| mediumslateblue      | `7B68EEFF` |
| mediumspringgreen    | `00FA9AFF` |
| mediumturquoise      | `48D1CCFF` |
| mediumvioletred      | `C71585FF` |
| midnightblue         | `191970FF` |
| mintcream            | `F5FFFAFF` |
| mistyrose            | `FFE4E1FF` |
| moccasin             | `FFE4B5FF` |
| navajowhite          | `FFDEADFF` |
| navy                 | `000080FF` |
| none                 | `000000FF` |
| oldlace              | `FDF5E6FF` |
| olive                | `808000FF` |
| olivedrab            | `6B8E23FF` |
| orange               | `FFA500FF` |
| orangered            | `FF4500FF` |
| orchid               | `DA70D6FF` |
| palegoldenrod        | `EEE8AAFF` |
| palegreen            | `98FB98FF` |
| paleturquoise        | `AFEEEEFF` |
| palevioletred        | `DB7093FF` |
| papayawhip           | `FFEFD5FF` |
| peachpuff            | `FFDAB9FF` |
| peru                 | `CD853FFF` |
| pink                 | `FFC0CBFF` |
| plum                 | `DDA0DDFF` |
| powderblue           | `B0E0E6FF` |
| purple               | `800080FF` |
| red                  | `FF0000FF` |
| rosybrown            | `BC8F8FFF` |
| royalblue            | `4169E1FF` |
| saddlebrown          | `8B4513FF` |
| salmon               | `FA8072FF` |
| sandybrown           | `F4A460FF` |
| seagreen             | `2E8B57FF` |
| seashell             | `FFF5EEFF` |
| sienna               | `A0522DFF` |
| silver               | `C0C0C0FF` |
| skyblue              | `87CEEBFF` |
| slateblue            | `6A5ACDFF` |
| slategray            | `708090FF` |
| slategrey            | `708090FF` |
| snow                 | `FFFAFAFF` |
| springgreen          | `00FF7FFF` |
| steelblue            | `4682B4FF` |
| tan                  | `D2B48CFF` |
| teal                 | `008080FF` |
| thistle              | `D8BFD8FF` |
| tomato               | `FF6347FF` |
| turquoise            | `40E0D0FF` |
| violet               | `EE82EEFF` |
| wheat                | `F5DEB3FF` |
| white                | `FFFFFFFF` |
| whitesmoke           | `F5F5F5FF` |
| yellow               | `FFFF00FF` |
| yellowgreen          | `9ACD32FF` |

---
# Deleting assets

Source: https://hygraph.com/docs/api-reference/assets/deleting-assets

Hygraph exposes a `deleteAsset` mutation that you can use to delete any unwanted assets.

Simply pass the `id` of the asset you want to delete:

```graphql
mutation {
  deleteAsset(where: { id: "..." }) {
    id
  }
}
```

<Alert theme="warning">
Deleting assets is a permanent change, and cannot be rolled back.
</Alert>

Learn more about [Mutations](/docs/api-reference/content-api/mutations#delete-entries).


---
# Embedded types

Source: https://hygraph.com/docs/api-reference/assets/embedded-types

Assets can be embedded into the [Rich Text Field Type](/docs/api-reference/schema/field-types#rich-text) via a configuration setting. On the API side, we create a union relation that references the selected model.

## Enable embedding

The first thing you need to do is configure your Rich Text field to allow embeds, and select **Asset** as embeddable model.

You will do this in the UI by navigating to your Schema, selecting the model your Rich Text field is in, and selecting the `Enable embedding` checkbox:

![Rich Text Options](/images/docs/api-reference/schema/rich-text-embed-options.png)

<Alert theme="info" title="Pro Tip">
**Rich text embeds need to be enabled per field**. You can do this from inside the **Field Settings** when adding a new, or editing a `Rich Text` field. Click `Enable embedding` and select the models that should be embeddable in your Rich text field.
</Alert>

## Create union relation

With Rich Text Embeds enabled, your API will have some new types added. The name of your field will be now a type appended by `RichText`, and `RichTextEmbeddedTypes` inside your schema.

For example, if you had the model `Post` and field `content`, the types generates would be `PostContentRichText`, and `PostContentRichTextEmbeddedTypes` respectively.

The `PostContentRichText` type will look like the following:

```graphql
type RichText {
  json: RichTextAST!
  html: String!
  markdown: String!
  text: String!
  references: [PostContentRichTextEmbeddedTypes!]!
}
```

The `references` field will be a union relation to the types you embedded, for example `Asset`.

You should use the `references` field when querying `JSON` to get the `URL` - with any [transformations](/docs/api-reference/assets/transformations), `handle`, or any of the [Asset fields](/docs/api-reference/schema/system-fields#asset-fields).

<Tabs panelHeight={420}>
  <TabsItem label="Query">

```graphql
{
  posts {
    content {
      json
      html
      markdown
      text
      references {
        __typename
        ... on Asset {
          url
          handle
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "posts": [
      {
        "content": {
          "json": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": "Hygraph Rich Text Embeds"
                  }
                ]
              },
              {
                "type": "embed",
                "nodeId": "cko2lq2u0031r0844xnvurz05",
                "children": [
                  {
                    "text": ""
                  }
                ],
                "nodeType": "Asset"
              },
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": ""
                  }
                ]
              }
            ]
          },
          "html": "<p>Hygraph Rich Text Embeds</p><div data-gcms-embed-type=\"Asset\" data-gcms-embed-id=\"cko2lq2u0031r0844xnvurz05\"></div><p></p>",
          "markdown": "Hygraph Rich Text Embeds\n\n\n",
          "text": "Hygraph Rich Text Embeds\\n\\n",
          "references": [
            {
              "__typename": "Asset",
              "url": "https://media.graphassets.com/xSIoGkATQybd8S2SgA5Q",
              "handle": "xSIoGkATQybd8S2SgA5Q"
            }
          ]
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The `HTML` response will return `gcms-embed-type` and `gcms-embed-id` data attributes for the embedded types. A block embed is returned as `div` and an inline embed as `span` with a `data-gcms-embed-inline` attribute. A link embed is returned as an `a`-tag with a `data-gcms-embed-id` and `data-gcms-embed-type` attribute.

<Tabs panelHeight={130}>
  <TabsItem label="Block">
    ```html
    <div
      data-gcms-embed-type="Asset"
      data-gcms-embed-id="cko2lq2u0031r0844xnvurz05"
    ></div>
    ```
  </TabsItem>
  <TabsItem label="Inline">
    ```html
    <span
      data-gcms-embed-type="Author"
      data-gcms-embed-id="ckwyytv5k003s0791zitq6alu"
      data-gcms-embed-inline
    ></span>
    ```
  </TabsItem>
  <TabsItem label="Link">
    ```html
    <a
      data-gcms-embed-id="cl0sa2kc50sb80axsu0kcaeaa"
      data-gcms-embed-type="Post"
    >
      link text
    </a>
    ```
  </TabsItem>
</Tabs>

Hygraph uses <Link href="https://docs.slatejs.org" target="_blank">Slate 0.5</Link> for `RichTextAST`.

<Alert theme="info">
If you are programmatically creating content entries with Rich Text, you should use the <Link href="https://github.com/hygraph/rich-text/tree/main/packages/html-to-slate-ast" target="_blank"><code>@graphcms/html-to-slate-ast</code></Link> package.
</Alert>

## Additional resources

- [Rich Text field:](/docs/api-reference/content-api/rich-text-field) Learn more about Hygraph's Rich Text field. The article covers Rich Text data, Rich Text embeds, and using your JSON representation of RTE for customization.
- <Link href="https://hygraph.com/blog/styling-rich-text-tailwindcss" target="_blank">Styling Rich Text with TailwindCSS:</Link> Detailed tutorial on how to use the `JSON` representation from the RTE to create custom elements for each text-based element of Rich Text.
- <Link href="https://hygraph.com/blog/hygraph-react-rich-text-renderer" target="_blank">Introducing the Hygraph React Rich Text Renderer:</Link> Blog post on how to render Hygraph documents using Rich Text in your application easily using our available packages.
- [Rich Text editor UI guide:](/docs/developer-guides/content/rich-text-editor) Guide on how to use Hygraph's Rich Text editor in the content editor of your project.


---
# Fetching assets

Source: https://hygraph.com/docs/api-reference/assets/fetching-assets

Hygraph automatically generates 4 query types for assets. These are:

![Asset queries](/images/docs/api-reference/assets/asset-queries.png)

- `asset`
- `assets`
- `assetVersion`
- `assetsConnection`

These queries work just like regular [queries](/docs/api-reference/content-api/queries), and can be [filtered](/docs/api-reference/content-api/filtering) by their [fields](/docs/api-reference/schema/field-types#asset).

Here are some sample queries:

<Tabs panelHeight={230}>
  <TabsItem label="asset">

```graphql
# Fetch the fileName, local, size and stage of the asset with the provided id
query MyQuery {
  asset(where: {id: "<YOUR_ASSET_ID>"}) {
    fileName
    locale
    size
    stage
    url
  }
}
```

  </TabsItem>
  <TabsItem label="assets">

```graphql
# Fetch the fileName, size and locale of all assets in stage PUBLISHED
query MyQuery {
  assets(stage: PUBLISHED) {
    fileName
    size
    locale
    url
  }
}
```

  </TabsItem>
  <TabsItem label="assetVersion">

```graphql
# Fetch an asset version, filtered by revision number, unique identifier, and stage
query MyQuery {
  assetVersion(
    where: {revision: 10, id: "<YOUR_ASSET_ID>", stage: DRAFT}
  ) {
    createdAt
    data
  }
}
```

  </TabsItem>
  <TabsItem label="assetsConnection">

```graphql
# Fetch assets with assetUploadStatus ASSET_CREATE_PENDING
query MyQuery {
  assetsConnection(where: {assetUploadStatus: ASSET_CREATE_PENDING}) {
    edges {
      node {
        id
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Generate URLs with file names

To enhance SEO and improve user trust, you can include the original file name in asset URLs generated via the new Hygraph Asset Management system.

1. Run the following query:

<Tabs panelHeight={230}>
  <TabsItem label="Query">

```graphql
# Fetch the url and fileName of the asset
query MyQuery {
  assets {
    url
    fileName
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://eu-central-1-shared-euc1-02.graphassets.com/cmbq7mmxm0nhp07uqduk/cmcaodlnt9vxpfhycpf4",
        "fileName": "content-finder.gif"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

2. Combine the `url` and `fileName` manually or via a script, separated by `/`. The final URL would look like this:

```url
https://eu-central-1-shared-euc1-02.graphassets.com/cmbq7mmxm0nhp07uqduk/cmcaodlnt9vxpfhycpf4/content-finder.gif
```

<Alert theme="info" title="Pro Tip">

Ensure that the file name and file extension (`jpg`, `webp`, etc.) matches the current version of the asset. If you convert a `jpg` to `webp` using URL transformations, then you need to update the extension at the end to `webp`.

</Alert>


---
# Localized assets

Source: https://hygraph.com/docs/api-reference/assets/localized-assets

<Alert theme="info">

If you want to find out which asset system your project uses and which section of this document applies to you, [click here](/docs/api-reference/assets/assets-overview#which-asset-system-does-my-project-use).

</Alert>

## Hygraph Asset Management

Our asset system lets you create a localizations by providing as `fileName` (optional) and `uploadUrl`. You can use the `createAsset` mutation and create the localization simultaneously, or use `updateAsset` and add a localization to an existing asset.

<Alert theme="info" title="Pro Tip">
If you don't pass a `fileName`, the system uses the file name of the file you provide - via URL or local file.

If you pass a `fileName`, it overwrites the name of the file you provide. 
</Alert>

The following example shows the URL upload of an asset along with its localized content:

```graphql
mutation test {
  createAsset(
    data: {
			uploadUrl: "<UPLOAD_URL>"
      localizations:{
        create: {
          locale: de
          data:{
            uploadUrl: "<LOCALE_UPLOAD_URL>"
          }
        }
      }
    }
  ) {
    id
    url
    localizations {
      id
      url
    }
  }
}
```

This other example updates an existing asset entry, adding the `de` localization:

```graphql
mutation test {
  updateAsset(
    where: {id: "<ASSET_ID>"}
    data: {
      localizations: {
        create: {
          locale: de, 
          data: { 
            uploadUrl: "<LOCALE_UPLOAD_URL>"
          }
        }
      }
    }
  ) {
    id
    locale
    url
    localizations {
      url
      locale
    }
  }
}
```

<Alert theme="info" title="Pro Tip">
For the action of creation of localized assets to work, your project configuration must already have the locale configured.
</Alert>

Learn more about [mutating localized content](/docs/api-reference/content-api/localization#mutating-localized-content).

## Legacy asset system

Since assets are localized by default, you can upload a file for your project locales.

You can do this from the UI: Simply navigate to **Assets** and access the edit view of your asset entry.

Click the eye icon next to your localization to ensure the `Upload` button is visible.

![Asset localization - Legacy asset system](/images/docs/api-reference/assets/asset-localization-legacy.png)

<Alert theme="info" title="Pro Tip">
Localizations only display on the sidebar if you've previously configured them in your project settings.
</Alert>

## Localize assets in the UI

You can also localize assets using the UI. [Check out this document to learn more](/docs/developer-guides/content/content-localization#adding-a-translation).

---
# Publishing assets

Source: https://hygraph.com/docs/api-reference/assets/publishing-assets

Since **Assets** is a system model, assets also come with publishing capabilities. You can use GraphQL mutations to publish or unpublish your assets, to and from content stages.


<Tabs panelHeight={200}>
  <TabsItem label="publishAsset">

```graphql
# Use the publishAsset mutation along with your asset ID and a destination stage to publish an asset to that stage
# This example publishes an asset to the PUBLISHED stage
mutation {
  publishAsset(where: {id: "<YOUR_ASSET_ID>"}, to: PUBLISHED) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="unpublishAsset">

```graphql
# Use the unpublishAsset mutation along with an asset ID to return the asset to the DRAFT stage
mutation {
  unpublishAsset(where: {id: "<YOUR_ASSET_ID>"}) {
    id
  }
}
```

  </TabsItem>
</Tabs>

Learn more about [publishing to content stages](/docs/api-reference/content-api/content-stages).


---
# Referencing assets

Source: https://hygraph.com/docs/api-reference/assets/referencing-assets

While you can query for individuals assets, or fetch all and filter, order, and paginate, assets are best used when related to another model.

When extending the Hygraph schema with your own models, the [Asset](/docs/api-reference/schema/field-types#asset) field type exposes all of the available transformations below.

For example, imagine you have a `Product` model with a [one to many](/docs/api-reference/schema/field-types#one-to-many) reference to assets, as `productImage`:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  product(where: {productSlug: "green-hoodie"}) {
    productImage {
      fileName
      height
      width
      size
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "product": {
      "productImage": [
        {
          "fileName": "green hoodie 3.jpg",
          "height": 3862,
          "width": 5856,
          "size": 4324263
        },
        {
          "fileName": "green hoodie 1.jpg",
          "height": 6720,
          "width": 4480,
          "size": 4989479
        },
        {
          "fileName": "green hoodie 2.jpg",
          "height": 6720,
          "width": 4480,
          "size": 4996739
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

You can query any of the [system fields](/docs/api-reference/schema/system-fields#asset-fields) here as well.

---
# Asset transformations

Source: https://hygraph.com/docs/api-reference/assets/transformations

When fetching assets, you can pass an optional `transformation` argument to the `url` field. Hygraph enforces [transformation safeguards](#transformation-safeguards) on requests and capacity. Breaches return `400 Bad Request` or `429 Too Many Requests`, depending on the safeguard.

<Alert theme="info">

If you want to find out which asset system your project uses and which section of this document applies to you, [click here](/docs/api-reference/assets/assets-overview#which-asset-system-does-my-project-use).

</Alert>

## Hygraph Asset Management

### Auto image

This document transformation uses the `auto_image` parameter to determine which [mimetype](/docs/api-reference/assets/transformations#file-type-conversion) to serve based on the browsers preference.

| Arg          | Description                                                                                                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_image` | Determines which mimetype to serve based on the browsers preference. We either send back a `webp` or an `avif`, depending on the **Accept** request header. Without an **Accept** header, we use `jpg` as fallback. |

For example:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        document: {output: {format: autoImage}}
        }
      )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/auto_image/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Blur

This transformation uses the `blur` parameter to blur your image.

| Arg      | Description                                                        |
| -------- | ------------------------------------------------------------------ |
| `amount` | Blur effect amount. The value must be an integer from `0` to `20`. |

For example, we can query all assets, and blur images to an amount of 4:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image: { blur: {amount: 4} }
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/blur=amount:4/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Border

This transformation uses the `border` parameter to control the width, color and background of your image borders.

| Arg          | Description                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `width`      | Border width. The value must be an integer from `1` to `1000`.                                                                 |
| `color`      | Border color. The value must be a hexadecimal or shortened hexadecimal color code.                                             |
| `background` | Border color. The value must be a hexadecimal or shortened hexadecimal color code, or a supported color name. [Here's a list of color names and their corresponding HEX values](/docs/api-reference/assets/border-hex-values) that you can use for your image borders. |

For example, we can query all assets, and set the image borders using our chosen characteristics:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image: { border: {width: 2, color: "gray15", background: "azure"} }
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/border=width:2,color:gray15,background:azure/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Compress

This transformation compresses PNG & JPG files.

| Arg        | Description                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `compress` | Image compression. You can choose to compress the metadata as well by passing `true` or `false`. |

<Alert theme="warning">
- `compress` will only work on `jpg` and `png` file formats, otherwise it returns unchanged.
- Make compress the last transformation in your chain for better results.
</Alert>

For example, we can query all assets, and compress images along with their metadata:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image:{compress:{metadata:true}}
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/compress=metadata:true/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Crop

This transformation uses the `crop` parameter to crop images by entering coordinates and crop dimensions:

- The starting points for `X` and `Y` coordinates are [0,0], aligning with the top-left corner of the image.
- The `width` and `height` parameters determine the size in pixels of the cropping rectangle. The output will include only the portion of the image within the designated crop area.

| Arg      | Description                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------- |
| `x`      | The `x` coordinate of the image. The value must be an integer from `0` to `10000`.             |
| `y`      | The `y` coordinate of the image. The value must be an integer from `0` to `10000`.             |
| `width`  | The width in pixels to resize the image to. The value must be an integer from `1` to `10000`.  |
| `height` | The height in pixels to resize the image to. The value must be an integer from `1` to `10000`. |

For example, we can query all assets, and crop images:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image:{crop:{ x: 100, y: 200, width:300, height: 400 }}
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "createdAt": "2024-01-19T13:56:45.723049+00:00",
        "url": "https://REGION.graphassets.com/ENV_ID/crop=dim:[100,200,300,400]/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Quality

Use the `quality` parameter to set the quality of your image without risking generating a larger file.

| Arg     | Description                                                                     |
| ------- | ------------------------------------------------------------------------------- |
| `value` | The quality value of the image. The value must be an integer from `1` to `100`. |

<Alert theme="info">
- Only supported for the following formats: `jpeg`, `jpg`, `webp`, `gif`, `heif`, `tiff`, `avif`
- You can use this transformation to reduce the file size of your image before a compress task.
</Alert>

For example, we can query all assets, and set the image quality to 50:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image: { quality: {value: 50} }
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/quality=value:50/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>


### Resize

This transformation uses the `resize` parameter to adjust the image `height`, `width` and `fit`.

The `image` takes the following arguments:

| Arg      | Type       | Description                                                                                                   |
| -------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `width`  | `Int`      | The width in pixels to resize the image to. The value must be an integer from `1` to `10000`.                 |
| `height` | `Int`      | The height in pixels to resize the image to. The value must be an integer from `1` to `10000`.                |
| `fit`    | `ImageFit` | The default value for this parameter is `clip`. Check the following table for all possible values. |

The `ImageFit` takes one of the following values:

| Value   | Description                                                                                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clip`  | Resizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio.                                                                                 |
| `crop`  | Resizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries.                                                                   |
| `scale` | Resizes the image to fit the specified parameters exactly by scaling the image to the desired size. The aspect ratio of the image is not respected and the image can be distorted using this method. |
| `max`   | Resizes the image to fit within the parameters, but as opposed to `fit:clip` will not scale the image if the image is smaller than the output size.                                                  |

<Alert theme="info">
Only supported for the following formats: `jpeg`, `jpg`, `png`, `gif`, `bmp` , `tiff`, `webp`, `avif`
</Alert>

For example, we can query all assets, and resize images:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image: { resize: { width: 50, height: 50, fit: clip } }
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/resize=fit:clip,height:50,width:50/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Sharpen

This transformation uses the `sharpen` parameter to sharpen your image.

| Arg      | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `amount` | Sharpen effect amount. The value must be an integer from `0` to `20`. |

For example, we can query all assets, and sharpen images to an amount of 2:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
{
  assets {
    url(
      transformation: {
        image: { sharpen: {amount: 2} }
      }
    )
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/sharpen=amount:2/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### File type conversion

The following table shows the original file type you'd be changing from, and the possible formats you'd change it into.

| Input type | Available output formats                           | Mimetype          |
| ---------- | -------------------------------------------------- | ----------------- |
| `AVIF`     | `JPG`, `PNG`, `WEBP`, `GIF`, `TIFF`                | `image/avif`      |
| `BMP`      | `JPG`, `PNG`, `SVG`, `WEBP`, `GIF`, `TIFF`, `AVIF` | `image/bmp`       |
| `GIF`      | `JPG`, `PNG`, `SVG`, `WEBP`, `TIFF`, `AVIF`        | `image/gif`       |
| `JPG`      | `PNG`, `SVG`, `WEBP`, `GIF`, `TIFF`, `AVIF`        | `image/jpg`       |
| `PDF`      | `JPG`, `GIF`, `WEBP`, `TIFF`, `AVIF`               | `application/pdf` |
| `PNG`      | `JPG`, `SVG`, `WEBP`, `GIF`, `TIFF`, `AVIF`        | `image/png`       |
| `SVG`      | `JPG`, `PNG`, `WEBP`, `GIF`, `TIFF`, `AVIF`        | `image/svg+xml`   |
| `TIFF`     | `JPG`, `PNG`, `SVG`, `WEBP`, `GIF`, `AVIF`         | `image/tiff`      |
| `WEBP`     | `JPG`, `PNG`, `SVG`, `GIF`, `TIFF`, `AVIF`         | `image/webp`      |

For example, we can query all assets, and convert the images to JPG:

<Tabs panelHeight={200}>
  <TabsItem label="Query">

```graphql
query Assets {
  assets {
    createdAt
    url(transformation: {document: {output: {format: jpg}}})
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "assets": [
      {
        "createdAt": "2024-01-19T13:56:45.723049+00:00",
        "url": "https://REGION.graphassets.com/ENV_ID/output=format:jpg/HANDLE"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### URL transformations

It is possible to do URL transformations without using the API. You can do this by using the regular URL of an asset and then placing the transformation syntax in it.

You would place the transformation here:

```
https://REGION.graphassets.dev/ENV_ID/<Transformations go here>/HANDLE
```

The following example uses `resize`:

```
https://REGION.graphassets.dev/ENV_ID/resize=width:400,height:400/HANDLE
```

You can also chain the transformations. The following example uses `resize` and `sharpen`:

```
https://REGION.graphassets.dev/ENV_ID/resize=width:400,height:400/sharpen=amount:2/HANDLE
```

## Transformation safeguards

Hygraph enforces safeguards on asset transformations to keep image processing fast and reliable for every project. Safeguards fall into two groups:

- **Request safeguards** validate what a transformation URL asks for: output dimensions, multi-page output, and how many times an operation may repeat. Breaches return `400 Bad Request` with a body beginning `"Asset transformation safeguard exceeded:"`.
- **Capacity safeguards** bound the work a transformation costs to produce: the resolution of the source asset, and how many *new* transformations a project may generate per second.

| Safeguard | Limit | Applies to | Response |
| --- | --- | --- | --- |
| Resize width / height | `10000` px each | Requested output | `400` |
| Multi-page output width / height | `2000` px each | Requested output | `400` |
| Multi-page upscaling factor | `3.0x` | Requested output | `400` |
| Repetitions per transformation kind | `3` | Transformation URL | `400` |
| Source resolution | `100` MP (`100,000,000` px) | Source asset | `400` |
| New transformations per second | `40` RPS shared / `80` RPS dedicated | Uncached transformations, per environment | `429` |

Safeguards apply to both GraphQL `url(transformation: {...})` queries and direct URL transformations. Transformations already generated and cached are unaffected by capacity safeguards.

### Resize safeguards

`resize.width` and `resize.height` are each capped at `10000` px. The value `10000` is accepted, any value above `10000` is rejected.

For example, `resize=width:15000` returns `Asset transformation safeguard exceeded: resize width 15000 must not exceed 10000`

### Multi-page asset safeguards

Multi-page assets include animated image formats and multi-page documents such as animated GIF, animated WebP, APNG, animated AVIF/HEIC/HEIF, multi-page TIFF, and PDF.

The following safeguards apply to all multi-page assets:

| Safeguard          | Value    |
| ------------------ | -------- |
| Maximum output width  | `2000` px |
| Maximum output height | `2000` px |
| Maximum upscaling factor | `3.0x` |

A request must satisfy all three safeguards. A request within the `2000` px dimension safeguards can still be rejected if it upscales the original by more than `3.0x`.

Example response bodies:
- `Asset transformation safeguard exceeded: multi-page width 3000 must not exceed 2000 for gif`
- `Asset transformation safeguard exceeded: multi-page upscaling factor 15.00 exceeds 3.00 for avif`

### Per-transformation repetition cap

Each transformation kind can appear at most `3` times in a single transformation URL. This safeguard is per kind, not per total transformation count.

The counted kinds are: `resize`, `output`, `blur`, `sharpen`, `border`, `quality`, `crop`, `compress`, and `cache`. 

A URL containing four `resize` transformations returns `Asset transformation safeguard exceeded: transformation kind - resize with value 4 exceeded its default limit: 3`

### Source resolution

A transformation decodes the entire source image into memory before touching it. File size is a poor predictor of that cost: a few-megabyte file can decode into a gigapixel image, which is not always intuitive the first time a small-looking upload trips this limit. Bounding resolution, rather than file size, is what reliably bounds the memory a single request can consume.

So, Hygraph caps the resolution of the **source image** a transformation may be applied to at **100 megapixels** (100,000,000 pixels, for example 10,000 × 10,000). Resolution is measured as `width × height` of the decoded image, per page. 

Your plan's asset upload limit governs how large a file you can **store**. The source resolution cap governs what the image pipeline will transform.

| Action | Asset above the source resolution cap |
| --- | --- |
| Uploading the asset | Allowed, up to your plan's upload limit |
| Serving or downloading the original | Works normally |
| Requesting a transformation of it | Returns `400 Bad Request` |

If your plan allows, you can still store, version, publish, and download assets above the source resolution cap at their original URL. But you cannot transform these assets.

For example, requesting a transformation of a 15,000 × 12,000 source image (180 MP) returns `Asset transformation safeguard exceeded: source image too large to transform: 180000000 pixels exceeds the 100000000 pixel limit`

Animated and multi-page assets are measured one page at a time, so frame count doesn't count against the cap. Such assets are bounded separately by the [multi-page safeguards](#multi-page-asset-safeguards).

#### Working with large source assets
 
- **Resize once, at ingest.** Store a web-scale master and keep the full-resolution file in your DAM or archive.
- **Serve the original where the full resolution matters.** The unmodified asset URL has no resolution cap. You can use it for download links, print assets, and archival access.
- **Re-upload a downscaled version** if you need transformations of an existing over-limit asset.

### Transformation rate limit

Generating a transformation that does not exist yet is a compute-intensive operation. To protect throughput across all projects, Hygraph applies a **requests-per-second (RPS) limit on new transformations**, counted per project environment.

| Deployment | New transformations per second, per environment |
| --- | --- |
| Shared clusters | 40 RPS |
| Dedicated clusters | 80 RPS |

The limit applies **only** when Hygraph has to generate a transformation it has not produced before. It does not apply to:

- **Cached transformations**: Any transformation already generated is served from the CDN with no limit and no rate-limit accounting.
- **Original asset requests**: Fetching the unmodified asset is never rate-limited.

In practice, this means production traffic is effectively unlimited: a page serving the same set of image variants to thousands of visitors generates one transformation per variant, then serves cached results indefinitely.

Unlike the request safeguards, a rate-limited response body does not begin with `"Asset transformation safeguard exceeded:"`. Detect it by the `429` status code.

For example, when an environment exceeds its allowance for new transformations, it returns `429 Too Many Requests` with a `Retry-After` header.

The `Retry-After` header gives the number of seconds to wait before retrying. The limit is measured over a one-second window, so allowances recover immediately. A short backoff and retry is the correct client behavior.

#### Staying within the limit

The limit counts *distinct new* transformations. Increase your cache hit rate to avoid being rate-limited.

- **Reuse a fixed set of variants.** Pick the sizes your layout needs (thumbnail, card, hero, and their 2× versions) and reuse those exact URLs everywhere. Repeat requests hit the cache.
- **Don't size images from runtime values.** Viewport width, device pixel ratio, or container size produce a near-unique URL per visitor, so each one triggers a new transformation. Use a fixed set of breakpoints instead.
- **Warm variants before a launch.** Request each new variant once, before a campaign, migration, or bulk import goes live. Don't let peak traffic generate them for the first time.
- **Throttle bulk jobs.** When transforming a whole asset library, limit concurrency and retry on `429` instead of firing every request at once.

## Validate transforms

We provide a validation field you can enable to check the combination of transform arguments are valid.

For example, you may query a video, and request to change the file type to PDF. `validateOptions: true` will warn you that this is not allowed.

```graphql
{
  assets {
    url(
      transformation: {
        document: { output: { format: pdf } }
        validateOptions: true
      }
    )
  }
}
```

## Combine transforms

It is possible to combine both transformation arguments:

```graphql
{
  assets {
    url(
      transformation: {
        image: { resize: { width: 50, height: 50, fit: clip } }
        document: { output: { format: png } }
        validateOptions: true
      }
    )
  }
}
```

## Alias transforms

[GraphQL aliases](/docs/api-reference/content-api/queries#combining-queries) are great for querying the same asset URL with multiple transformations.

For example, you could transform product images to include a `thumbnail`.

```graphql
{
  products {
    images {
      thumbnail: url(
        transformation: {
          image: { resize: { width: 50, height: 50, fit: clip } }
          document: { output: { format: png } }
        }
      )
      url(transformation: { document: { output: { format: png } } })
    }
  }
}
```

## Legacy asset system

### Resize images

The `image` takes the following arguments:

| Arg      | Type       | Description                                                                                    |
| -------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `width`  | `Int`      | The width in pixels to resize the image to. The value must be an integer from `1` to `10000`.  |
| `height` | `Int`      | The height in pixels to resize the image to. The value must be an integer from `1` to `10000`. |
| `fit`    | `ImageFit` | The default value for the fit parameter is `clip`.                                             |

The `ImageFit` takes one of the following values:

| Value   | Description                                                                                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clip`  | Resizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio.                                                                                 |
| `crop`  | Resizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries.                                                                   |
| `scale` | Resizes the image to fit the specified parameters exactly by scaling the image to the desired size. The aspect ratio of the image is not respected and the image can be distorted using this method. |
| `max`   | Resizes the image to fit within the parameters, but as opposed to `fit:clip` will not scale the image if the image is smaller than the output size.                                                  |

For example, we can query all assets, and resize images:

```graphql
{
  assets {
    url(
      transformation: {
        image: { resize: { width: 50, height: 50, fit: clip } }
      }
    )
  }
}
```

### Convert file type

Depending on the asset type you're dealing with, it's possible to transform the `output` to another file type by passing a `format` value.

| Current file type | Available output formats                                         |
| ----------------- | ---------------------------------------------------------------- |
| PDF               | `jpg`, `odp`, `ods`, `odt`, `png`, `svg`, `txt`, `webp`          |
| DOC               | `docx`, `html`, `jpg`, `odt`, `pdf`, `png`, `svg`, `txt`, `webp` |
| DOCX              | `doc`, `html`, `jpg`, `odt`, `pdf`, `png`, `svg`, `txt`, `webp`  |
| ODT               | `doc`, `docx`, `html`, `jpg`, `pdf`, `png`, `svg`, `txt`, `webp` |
| XLS               | `jpg`, `pdf`, `ods`, `png`, `svg`, `xlsx`, `webp`                |
| XLSX              | `jpg`, `pdf`, `ods`, `png`, `svg`, `xls`, `webp`                 |
| ODS               | `jpg`, `pdf`, `png`, `xls`, `svg`, `xlsx`, `webp`                |
| PPT               | `jpg`, `odp`, `pdf`, `png`, `svg`, `pptx`, `webp`                |
| PPTX              | `jpg`, `odp`, `pdf`, `png`, `svg`, `ppt`, `webp`                 |
| ODP               | `jpg`, `pdf`, `png`, `ppt`, `svg`, `pptx`, `webp`                |
| BMP               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| GIF               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| JPG               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| PNG               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| WEBP              | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| TIFF              | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| AI                | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| PSD               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| SVG               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `webp`                 |
| HTML              | `jpg`, `odt`, `pdf`, `svg`, `txt`, `webp`                        |
| TXT               | `jpg`, `html`, `odt`, `pdf`, `svg`, `webp`                       |

For example, let's transform all assets to PDFs:

```graphql
{
  assets {
    url(transformation: { document: { output: { format: pdf } } })
  }
}
```

---
# Updating assets

Source: https://hygraph.com/docs/api-reference/assets/updating-assets

## Overview

Since assets are a system model, and automatically added to every project, you can extend them with your own custom fields.

These fields can be updated using GraphQL mutations. 

<Alert theme="info" title="Webhooks & asset updates">

Make sure you read our [webhooks documentation](/docs/api-reference/basics/webhooks#webhooks-and-assets) to understand how they work with the Hygraph Asset Management System.

</Alert>

## Update metadata

In the following example, we have added `altText` and `caption` fields to our **Assets** model. Here, we are using an `updateAsset` mutation to change the text in them:

<Tabs panelHeight={230}>
  <TabsItem label="Mutation">

```graphql
mutation {
  updateAsset(
    where: {id: "<YOUR_ASSET_ID>"}
    data: {caption: "this is a new caption", altText: "this is new alternative text"}
  ) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "updateAsset": {
      "id": "<YOUR_ASSET_ID>"
    }
  }
}
```

  </TabsItem>
</Tabs>

After successfully running this mutation, if you access your asset in edit mode, you will see the new `altText` and `caption`.

Learn more about [Mutations](/docs/api-reference/content-api/mutations#update-entries).

## Update existing asset

The Hygraph Asset Management System offers a way to update an existing asset entry and reuploading a new file for it.

To do this, there is a route to do a file upload, or a remote URL upload.

### Update via remote URL

Use `reUpload: true` as follows:

```graphql
mutation test {
  updateAsset(
    where: {id: "<YOUR_ASSET_ID>"}
    data: {reUpload: true, uploadUrl: "<NEW_ASSET_URL>"}
  ) {
    id
    upload {
      status
      expiresAt
      error {
        code
        message
      }
    }
  }
}
```

### Update via file upload

To update an asset via file upload you need to follow the [asset upload async process](/docs/api-reference/assets/uploading-assets#upload-by-file), with the data you get from `requestPostData` to send the local file to S3.

Use `reUpload: true` as follows:

```graphql
mutation test {
  updateAsset(where: {id: "<YOUR_ASSET_ID>"}, data: {reUpload: true}) {
    id
    upload {
      status
      expiresAt
      error {
        code
        message
      }
      requestPostData {
        url
        date
        key
        signature
        algorithm
        policy
        credential
        securityToken
      }
    }
  }
}
```


---
# Uploading assets

Source: https://hygraph.com/docs/api-reference/assets/uploading-assets

<Alert theme="info">

If you want to find out which asset system your project uses and which section of this document applies to you, [click here](/docs/api-reference/assets/assets-overview#which-asset-system-does-my-project-use).

</Alert>

Our asset system uses AWS S3's pre-signed upload URLs and includes the upload action into the GraphQL API.

This process will cover the following steps:

1. Send a `createAsset` mutation passing some basic information about the asset. This also works as a nested mutation.
2. You can [upload by file](/docs/api-reference/assets/uploading-assets#upload-by-file) or [by URL](/docs/api-reference/assets/uploading-assets#upload-by-remote-url). The upload works differently depending on your choice.
3. As soon as that the upload complete, the asset entry will switch from an internal  `ASSET_CREATE_PENDING` state to `ASSET_CREATE_COMPLETE`, and the asset will be served via its URL.

<Alert theme="info" title="Webhooks & asset uploads">

Make sure you read our [webhooks documentation](/docs/api-reference/basics/webhooks#webhooks-and-assets) to understand how they work with the Hygraph Asset Management System.

</Alert>

### Upload by file

This is a two-step process:

1. Create the asset via GraphQL mutation. This returns a URL that needs to be called to execute the upload.
3. Use that pre-signed URL to upload the asset file. The asset stays pending until the file gets successfully uploaded and analysed.

<Alert theme="info">
Size limits for uploaded files depend on the plan. <Link href="https://hygraph.com/pricing" target="_blank">Check out our pricing page.</Link>
</Alert>

#### Create asset via GraphQL mutation

The first step is to create the actual asset.

<Alert theme="info" title="Pro Tip">
If you don't pass a `fileName`, the system uses the file name of the file you provide - via URL or local file.

If you pass a `fileName`, it overwrites the name of the file you provide. You will need to add it to `data`.
</Alert>

Here's a sample mutation to create an asset called `test.jpg`, and the JSON response:

<Tabs panelHeight={380}>
  <TabsItem label="Mutation">

```graphql
mutation createAsset {
  createAsset(data: {}) {
    id
    url
    upload {
      status
      expiresAt
      error {
        code
        message
      }
      requestPostData {
        url
        date
        key
        signature
        algorithm
        policy
        credential
        securityToken
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "createAsset": {
      "id": "clt47n0t600j807vvirlzi1xx",
      "url": "https://eu-central-1.graphassets.com/clpqzrnm4007e01t810b59ir4/clt47n0t600j907vveibipmov",
      "upload": {
        "status": "ASSET_CREATE_PENDING",
        "expiresAt": "2024-02-27T12:38:49+00:00",
        "error": null,
        "requestPostData": {
          "url": "https://eu-1-assets-delivery-hg75hf.s3.eu-central-1.amazonaws.com",
          "date": "20240227T101349Z",
          "key": "clpqzrnm4007e01t810b59ir4/upload/clpqzrnh4001q01t84tl21zdl/clpqzrnh6001u01t866zfftoa/clt47n0t600j907vveibipmov/${filename}",
          "signature": "c17e7b1c5d4af665a8fc74421fae53b72e94bb19e85e7befd1eb79b865bef7d2",
          "algorithm": "AWS4-HMAC-SHA256",
          "policy": "eyJleHBpcmF0aW9uIjoiMjAyNC0wMi0yN1QxMjozODo0OS45MTRaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZGV2LTEtYXNzZXRzLWRlbGl2ZXJ5LWY3OGM1YjUifSx7ImtleSI8ImNscHF6cm5tNDAwN2UwMXQ4MTBiNTlpcjQvdXBsb2FkL2NscHF6cm5oNDAwMXEwMXQ4NHRsMjF6ZGwvY2xwcXpybmg2MDAxdTAxdDg2NnpmZnRvYS9jbHQ0N24wdDYwMGo5MDd2dmVpYmlwbW92LyR7ZmlsZW5hbWV9In0seyJ7LWFtei1hbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQVNJQVZRUkUzVk1FV0dZNUMyWEwvMjAyNDAyMjcvZXUtY2VudHJhbC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotZGF0ZSI6IjIwMjQwMjI3VDEwMTM0OVoifSx7IngtYW16LXNlY3VyaXR5LXRva2VuIjoiSVFvSmIzSnBaMmx1WDJWakVPci8vLy8vLy8vLy93RWFER1YxTFdObGJuUnlZV3d0TVNKSE1FVUNJRVppa0hoNmIrM1lZWWJyU2xFaWtpZWwvVnZZdCs0SEpWTE5QcFFzZ0tibkFpRUFnUldLdURxR3AzRUJic3A2MTRFUTZwMGs2RnoweS9mdDhLRk1USTltUmVzcS9RTUkwLy8vLy8vLy8vLy9BUkFGR2dadd3ek56a3hNRGd4TnpRMk1ERWlERTJPSWF5RDNEQXI3cE9OSVNyUkExYk1haXdON1FZSW5SSjNuby8vY0F3cm0rbjg0SVZOdWsraER3QXR2SG54aWxDcCtNZktlMVh6MTN1TWhrTWNGa1c2T2NGZXF1R09lUHJYV28yNjdEaXlKRkE0V0dqU3dxem8xVFRWUjhJTkZoaUJlWmdxa2Q4bEtZQnVRYzBsbWxIekhLamk1WVloYStVZG45L1BrRit3dlp5ZFF6Qk53NzJzakEwT2QrakxaUEhuR29kK2Z3WjFUT2o5RE4zd3NQb2E0MTU3OFBvU1ZSRzB1ZGN4RGFHejVxeFh6OXZvb2cwQ3pTVlFiUk1tNW1UTHdSelp3ZlJYMTQ0U2NxMUsrYVNMVE9UdW1mYzROTjFzdlVEODZ0VU51azFGVUxzOE5FZi9PcFlhZmcwMkhyWkEvRHlDSnhlS3A1SkRxRndCMGJZL2lUcTRqS1VLOFBDQXF1T3Q2bFRQRWRTTFJhTnVBSW43cWd6UFNmRi8rQ3JjREtEblZTWmlNR3VhSlA1cmhjUlRob01XdHFjKzdiL3pPNjhMNVdrL0o5SGtmZzNjNmh5UGlsTkRhMG1RY0lhU0VzT0dFTkhQL2Q5K2xJSUhJZWJXNDFmT3VMSVltWEJlaWVGTzFYNDRmbk5Ld0F2bDlkNkxmQTZxdiswNlJtSFdRYkg5VjdLNmRiOHp4ZDNYMDFXRldTckVKdEFEU2xRNkdvejdNRmtIaVk2SnF2NEpjWnJlV1pVTXhFSTgydEVRWWR6R3lwdmh1ZEd6TDhJR3k4QmpjcnFQakhMWjRRUTRMaW9hcS95czNrM1BSZ1QwcEtIT0RMNm5jK1E2cmpDUTR2YXVCanFsQWQ2VmxidGxvYXpFWlc1SUhqRGFVYTk3VjFwV3UxamxVTlN0dDNLNVZmeDJRWlNtdXdUdDl3bitQYzJZL0xpMDExU0pSYWZCZy9oQlhmMWpDTG4yZ2lLMkFuMEovWGxnZ3FQSmdUYnhydS83RThsTFdmOG9uL1g4aVc1V1AxNDZOMjVaZk0xdXh0RGNQNTB5eWhGemFaOGRjR1p3c1FFRjY3b01mNSsxN3JiVC9kT2k3WkE1RTFLVG4vbmJMZUVhcEhZckQ5SkJESUtTZjRyaWhyLzkzcUtYTjFWajh3PT0ifV19",
          "credential": "AFDGAVRRE3VMFWGY5C2XL/20240227/eu-central-1/s3/aws4_request",
          "securityToken": "IQoJb3JpZ2luX2VjEOr//////////wEaDGV1LWNlbnRyYWwtMSJHMEUCIEZikHh6b+3YYYbrSlEikiel/VvYt+4HJVLNPpQsgKbnAiEAgRWKuDqGp3EBbsp614EQ6p0k6Fz0y/ft8KFMTI9mResq/QMI0///////////ARAFGgwzNzkxMDgxNzQ2MDEiDE2OIayD3DAr7pONISrRA1bMaiwN7QYInRJ3no//cAwrm+n84IVNuk+hDwAtvHnxilCp+MfKe1Xz13uFhiBeZgqkd8lKYBuQc0lmlHzHKji5n9/PkF+wvZydQzBNw72sjA0Od+jLZPHnGod+fwZ1TOj9DN3wsPoa41578PoSVRG0udcxDaGz5qxXz9voog0CzSVQbRMm5mTLwRzZwfRX144Scq1K+aSLTOTumfc4NN1svUD86tUNuk1FULs8NEf/OpYafg02HrZA/DyCJxesdgsdgerKp5JDqFwB0bY/iTq4jKUK8PCAquOt6lTPEdSLRaNuAIn7qgzPSfF/+CrcDKDnVSZiMGuaJP5rhcRThoMWtqc+7b/zO68L5Wk/J9Hkfg3c6hyPilNDa0mQcIaSEsOGENHP/d9+lIIHIebW41fOuLIYmXBeieFO1X44fnNKwAvl9d6LfA6qv+06RmHWQbH9V7K6db8zxd3X01WFWSrEJtADSlQ6y8BjcrqPjHLZ4QQ4Lioaq/ys3k3PRgT0pKHODL6nc+Q6rjCQ4vauBjqlAd6VlbtloazEZW5IHjDaUa97V1pWu1jlUNStt3K5Vfx2QZSmuwTt9wn+Pc2Y/Li011SJRafBg/hBXf1jCLn2giK2An0J/XlggqPJgTbxru/7E8lLWf8on/X8iW5WP146N25ZfM1uxtDcP50yyhFzaZ8dcGZwsQEF67oMf5+17rbT/dOi7ZA5E1KTn/nbLeEapHYrD9JBDIKSf4rihr/93qKXN1Vj8w=="
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="warning">
Regarding the expiry of the `requestPostData` information:

You can use the `expiresAt` field for this.

If you use the `requestPost` info after that date, it will fail.
</Alert>

#### Upload asset

We will use curl for this example.

Imagine we extracted the `data.createAsset.upload.requestPostData` subkeys into variables, and we have a file `test.jpg` in our current working directory:

```bash
URL="https://dev-1-assets-delivery-f78c5b5.s3.eu-central-1.amazonaws.com"
DATE="20240123T173451Z"
KEY="clr7o58jb00w701vwhpc69xda/upload/clr7o587k000j01uhul69p0rb/clr7o58ca00qi01vw7wzoguau/clrqmzdpn00id0bvucez7gnm9"
SIGNATURE="3f812cc0b05d59ee3d1efdd9dc046ed6edf595749c2763b85b923133a84e8d86"
ALGORITHM="AWS4-HMAC-SHA256"
POLICY="eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0yM1QxOTo1OTo1MS45NDdaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZGV2LTEtYXNzZXRzLWRlbGl2ZXJ5LWY3OGM1YjUifSx7ImtleSI6ImNscjdvNThqYjAwdzcwMXZ3aHBjNjl4ZGEvdXBsb2FkL2NscjdvNTg3azAwMGowMXVodWw2OXAwcmIvY2xyN281OGNhMDBxaTAxdnc3d3pvZ3VhdS9jbHJxbXpkcG4wMGlkMGJ2dWNlejdnbm05In0seyJ4LWFtei1hbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQVNJQVZRUkUzVk1FMkJHWVZLT1AvMjAyNDAxMjMvZXUtY2VudHJhbC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotZGF0ZSI6IjIwMjQwMTIzVDE3MzQ1MVoifSx7IngtYW16LXNlY3VyaXR5LXRva2VuIjoiSVFvSmIzSnBaMmx1WDJWakVLci8vLy8vLy8vLy93RWFER1YxTFdObGJuUnlZV3d0TVNKSE1FVUNJRUF6SFQ2OUdEWm9CcXp5Nkw4bExDUDFEZnNBZ3FaM0phRms0M3ZvcGNGRUFpRUFrVTljUVNTSTFCRmV5TVZjTEI1QkFrVzg3NUE2M2hkWTVnNDgxcEY4QitNcTlBTUlZeEFGR2d3ek56a3hNRGd4TnpRMk1ERWlERkxzOHB2a0JHRU9aV3dSZVNyUkF4amJvVXRobDRtRUM3VHVzTHpFcXc1T1JUOUZRSStYYVVQWXZRZi9ST3ZNOExBVkFYVHQwMWZHT0JyUkVRSDRDckJLSVVtMDNtQWFPd05nQ2g1aGFlTDhmTzZvRUJ3aTFLa2ZuRWpNWmtQcVJma0krMDZhK0o0SVBYTmR0bEt6b0VVOVd4Uk9TMzEyTC8rMjBpUkpLNmNoWmhhK04zVXNJMzRYR0U0L2IzNzV0aXpsWUx0RHJYN0JiMXFIdFVNYlg3VWVUaVJaSDU4S1VwRjloK2QyWWk2bUhuL1lGcmJVaGpOcjVGL1pkL2FkdU5nOGpKU3liVkw5bTVZdWQvdlI3enMyNXdpYlpJK3BOQjFXcVZzRWtiN09EN2g1QjFlQkE5dnNMdzBKdVlFMmFnYm0xNjF0SjZVS3A5Tkd4YmVWaFM1TjQ5N2txV2MzN3pCT3ZxdWxUU1JHUW04V1QrNGx1YzZyd2VTT0lFeUxMaFowT1ZCSWM1Q0Nrc1YvaFAxT2dxeUdSNGdKTDlwa3RhUDl0encxaFhyUHJhUW1mRHhoaVgrUStaNitkSWFxalY2VGlwcVhqTk9jM2tFSFIwNmpydnlhOVFsRGxXaWd2eGRaTHkwZktzQW8vR0dBTlhlM2ZGSzhVclVObE4ySHFGeHpBYU9JNEJPMmU1VE1sUzA5MTZZTFZUN1Zxd3hHOHQ0NTlUTUFLcXpJMTJ4N2JTbHFYQ0lHUlc1anlsazhaTE1mbGRZS2t6eDN6dWNKZDYvYVN4Q1c1bE1pa2lGRjYrbW9WQW9kck1qeGhLZW42QnNRZ3ZMVW1kamFmaVROMkRERDhMK3RCanFsQVRzWGdYUmdZOUVJQzJMUXEyOU0xSGRlbmViY3I5YU5JbmFBTVFKRlpMUnl1bnM3dzk0MnhjaW1sSTYyak15RWFUczRZM3M3aTMwYVpqc1E2ampMK1hKMVJTQW5Ta2lndFJZbHVKSGFlaWJkRDMydEZDamZhY3ovZWF5eVhGcEgzekc5NHJRZUk1V0ZBWVZXRFZyWEN2WmJROG9SejV4OHN5ZFBBZWROR1VEOHYrMk5XWDc0NTBTcXdXc2Jta0dlekxoZ0pzNkxyOVhSSG5rTEljdGFoUDVoazg0Q3p3PT0ifV19"
CREDENTIAL="ASIAVQRE3VME2BGYVKOP/20240123/eu-central-1/s3/aws4_request"
SECURITY_TOKEN="IQoJb3JpZ2luX2VjEKr//////////wEaDGV1LWNlbnRyYWwtMSJHMEUCIEAzHT69GDZoBqzy6L8lLCP1DfsAgqZ3JaFk43vopcFEAiEAkU9cQSSI1BFeyMVcLB5BAkW875A63hdY5g481pF8B+Mq9AMIYxAFGgwzNzkxMDgxNzQ2MDEiDFLs8pvkBGEOZWwReSrRAxjboUthl4mEC7TusLzEqw5ORT9FQI+XaUPYvQf/ROvM8LAVAXTt01fGOBrREQH4CrBKIUm03mAaOwNgCh5haeL8fO6oEBwi1KkfnEjMZkPqRfkI+06a+J4IPXNdtlKzoEU9WxROS312L/+20iRJK6chZha+N3UsI34XGE4/b375tizlYLtDrX7Bb1qHtUMbX7UeTiRZH58KUpF9h+d2Yi6mHn/YFrbUhjNr5F/Zd/aduNg8jJSybVL9m5Yud/vR7zs25wibZI+pNB1WqVsEkb7OD7h5B1eBA9vsLw0JuYE2agbm161tJ6UKp9NGxbeVhS5N497kqWc37zBOvqulTSRGQm8WT+4luc6rweSOIEyLLhZ0OVBIc5CCksV/hP1OgqyGR4gJL9pktaP9tzw1hXrPraQmfDxhiX+Q+Z6+dIaqjV6TipqXjNOc3kEHR06jrvya9QlDlWigvxdZLy0fKsAo/GGANXe3fFK8UrUNlN2HqFxzAaOI4BO2e5TMlS0916YLVT7VqwxG8t459TMAKqzI12x7bSlqXCIGRW5jylk8ZLMfldYKkzx3zucJd6/aSxCW5lMikiFF6+moVAodrMjxhKen6BsQgvLUmdjafiTN2DDD8L+tBjqlATsXgXRgY9EIC2LQq29M1Hdenebcr9aNInaAMQJFZLRyuns7w942xcimlI62jMyEaTs4Y3s7i30aZjsQ6jjL+XJ1RSAnSkigtRYluJHaeibdD32tFCjfacz/eayyXFpH3zG94rQeI5WFAYVWDVrXCvZbQ8oRz5x8sydPAedNGUD8v+2NWX7450SqwWsbmkGezLhgJs6Lr9XRHnkLIctahP5hk84Czw=="

curl --request POST \
  --url $URL
  --form X-Amz-Date=$DATE
  --form key=$KEY
  --form X-Amz-Signature=$SIGNATURE
  --form X-Amz-Algorithm=$ALGORITHM
  --form policy=$POLICY
  --form X-Amz-Credential=$CREDENTIAL
  --form X-Amz-Security-Token=$SECURITY_TOKEN
  --form file=@./test.jpg
```

<Alert theme="warning">
You must put the `file` as last form entry. All other form entries must come before it.
</Alert>

The system also allows you to reupload a file for an existing asset entry. [Click here to know more.](/docs/api-reference/assets/updating-assets#update-existing-asset)

### Upload by remote URL

You can upload assets by remote URL in the GraphQL API by passing the URL of an asset hosted somewhere publicly accessible in the `createAsset` mutation.

```graphql
mutation test {
  createAsset(
    data: {
			uploadUrl:"https://images.unsplash.com/photo-1682687218147-9806132dc697"
    }
  ) {
    id
    url
  }
}
```

<Alert theme="warning">
As this is an asynchronous process, the image may still become `PENDING` until fully uploaded.
</Alert>

The system also allows you to reupload a file for an existing asset entry. [Click here to know more.](/docs/api-reference/assets/updating-assets#update-existing-asset)

## Legacy asset system

Hygraph supports uploading assets via HTTP. You'll need a [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens) with **Mutations** API access enabled to upload by file, or URL.

Assets are treated just like any other content entry, so they are automatically bound to the [environment](/docs/api-reference/basics/environments), and [authorization](/docs/api-reference/basics/authorization) settings of your project.

<Alert theme="warning">
- You must append `/upload` to your project API endpoint when uploading assets. For example, `https://[region].hygraph.com/v2/[projectId]/[environment]/upload`.
- You can upload assets to your project without the need of a [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens) by adding Read and Create permissions to the Content API. **This is however unsafe and not advised**, as exposing the endpoint anywhere - like your website - while having any write access on the Public API, would essentially allow anyone to modify your data.
</Alert>

### Upload by file (Legacy)

<Alert theme="info">
Size limits for uploaded files depend on the plan. <Link href="https://hygraph.com/pricing" target="_blank">Check out our pricing page.</Link>
</Alert>

<Tabs panelHeight={100}>
  <TabsItem label="cURL">

```bash
curl -XPOST -H "Authorization: Bearer {YOUR_PAT_VALUE}" -F fileUpload=@picture.jpg https://[region].hygraph.com/v2/[projectId]/[environment]/upload
```

  </TabsItem>
  <TabsItem label="Node.js">

```js
// Your file must have the .mjs extension because node-fetch is an ESM-only package.
import fetch, { FormData, fileFrom } from 'node-fetch';

const form = new FormData();

form.set('fileUpload', await fileFrom('path/to/file.png'));

fetch(`${process.env.HYGRAPH_URL}/upload`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HYGRAPH_ASSET_TOKEN}`,
  },
  body: form,
})
  .then((res) => res.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)))
  .catch((err) => console.log(err));
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "filename": "pexels-photo-1170986.jpeg",
  "mimetype": "image/jpeg",
  "size": 32476,
  "width": 500,
  "height": 750,
  "url": "https://media.graphassets.com/P3TkBzxyQLupgDWNFydB",
  "id": "ckfdz530o0001ip92cdr3bbmj"
}
```

  </TabsItem>
</Tabs>

Here's also a standard JavaScript example:

```js
const HYGRAPH_URL = '';
const HYGRAPH_ASSET_TOKEN = '';

async function upload() {
  const input = document.getElementById('fileUpload');
  const file = input.files[0];

  const form = new FormData();

  form.append('fileUpload', file);

  // It is not recommended to use the HYGRAPH_ASSET_TOKEN in the Front-End.
  // In this example we're using it, but in a real application you should
  // use a backend to upload the file and use the HYGRAPH_ASSET_TOKEN there.
  const response = await fetch(`${HYGRAPH_URL}/upload`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${HYGRAPH_ASSET_TOKEN}`,
    },
    body: form,
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
}
```

### Upload by remote URL (Legacy)

You can also upload files by providing a remote URL, instead of a file.

<Tabs panelHeight={100}>
  <TabsItem label="cURL">

```bash
curl -XPOST -d url=https://media.graphassets.com/P3TkBzxyQLupgDWNFydB https://[region].hygraph.com/v2/[projectId]/[environment]/upload
```

  </TabsItem>
  <TabsItem label="Node.js">

```js
// Your file need to have the .mjs extension because node-fetch is an ESM-only package.
import fetch from 'node-fetch';

fetch(`${process.env.HYGRAPH_URL}/upload`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HYGRAPH_ASSET_TOKEN}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: `url=${encodeURIComponent(
    'https://media.graphassets.com/P3TkBzxyQLupgDWNFydB'
  )}`,
})
  .then((res) => res.json())
  .then((data) => console.log(JSON.stringify(data, null, 2)))
  .catch((err) => console.log(err));
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "filename": "pexels-photo-1170986.jpeg",
  "mimetype": "image/jpeg",
  "size": 32476,
  "width": 500,
  "height": 750,
  "url": "https://media.graphassets.com/J9BOEF3OSuuSXDhvriQa",
  "id": "ckgs20b80017109547vfev24c"
}
```

  </TabsItem>
</Tabs>


---
# API Limits

Source: https://hygraph.com/docs/api-reference/basics/api-limits

API limits are technical safeguards that ensure your GraphQL API performs optimally and remains available for all users. These limits guard against common problems, such as big requests, inefficient queries, or high traffic, that could otherwise impact performance.

<Alert theme="info">
We do not enforce any limits on requests that hit our [CDN cache](/docs/api-reference/basics/caching). API limits are enforced on all uncached GraphQL queries for shared regions. The rate limiting depends on the current load of the shared region and the subscription plan. These limits can be lifted on dedicated clusters and enterprise plans. You can [contact sales](/contact) to request a custom plan.

</Alert>

## Request size

The maximum size of GraphQL queries and mutations, including the text and variables, as it reaches our API. This helps prevent oversized requests that could slow down your API. When you exceed this limit, you'll get a [`413 error`](/docs/api-reference/basics/errors#413-payload-too-large).

| Plan  | Limit                  |
| ----- | ---------------------- |
| Hobby | <ul><li>Queries: 10 KB </li><li>Mutations: 30 KB </li></ul>|
| Growth | <ul><li>Queries: 15 KB </li><li>Mutations: 70 KB </li></ul>|
| Enterprise | <ul><li>Queries: 20 KB </li><li>Mutations: 80 KB </li></ul> |

Follow these steps to check your query/ mutation request size.
1. In your browser, go to **Developer Tools > Network**.
2. Run the GraphQL request in the [API Playground](/docs/api-reference/basics/api-playground).
3. Click on the request and check the **Request Payload** or **Size** column.
4. Compare the size against our limits.

We recommend that you:
- Test your queries against limits during development.
- Break large queries into smaller, focused requests.
  For example: Instead of a query like this:

    <Tabs panelHeight={420}>
      <TabsItem label="Before - A large query">

    ```graphql
    query DashboardData($userId: ID!) {
      user(id: $userId) {
        id
        name
        email
        avatar { url width height }
        settings {
          locale
          timezone
          notifications { marketing product updates security }
        }
        followers(first: 200) {
          nodes { id name avatar { url } }
        }
        posts(first: 50) {
          nodes {
            id
            title
            slug
            excerpt
            body
            coverImage { url width height }
            tags { id name }
            author { id name avatar { url } }
            comments(first: 200) {
              nodes {
                id
                body
                createdAt
                author { id name }
              }
            }
          }
        }
        notifications(first: 100) {
          nodes { id type message createdAt readAt }
        }
      }
    }
    ```

      </TabsItem>
    </Tabs>

    You can split it into three separate queries:

    <Tabs panelHeight={250}>
      <TabsItem label="Query 1">

    ```graphql
    # Request 1: lightweight user profile
    query UserProfile($userId: ID!) {
      user(id: $userId) {
        id
        name
        avatar { url }
        settings { locale timezone }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Query 2">

    ```graphql
    # Request 2: concise posts list for the dashboard
    query UserPostsList($userId: ID!) {
      user(id: $userId) {
        id
        posts(first: 20) {
          nodes { id title slug excerpt coverImage { url } }
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Query 3">

    ```graphql
    # Request 3: fetch comments on-demand (example, when opening a post)
    query PostComments($postId: ID!) {
      post(id: $postId) {
        id
        comments(first: 20) {
          nodes {
            id
            body
            createdAt
            author { id name }
          }
        }
      }
    }
    ```

      </TabsItem>
    </Tabs>

- Use GraphQL fragments to avoid repetition.
  For example: Instead of a query like this:

    <Tabs panelHeight={420}>
      <TabsItem label="Before">

    ```graphql
    query ArticlePage($id: ID!) {
      post(id: $id) {
        id
        title
        author {
          id
          name
          username
          avatar { url width height }
        }
        lastEditor {
          id
          name
          username
          avatar { url width height }
        }
        comments(first: 20) {
          nodes {
            id
            body
            author {
              id
              name
              username
              avatar { url width height }
            }
          }
        }
      }
      me {
        id
        name
        username
        avatar { url width height }
        followers(first: 10) {
          nodes {
            id
            name
            username
            avatar { url width height }
          }
        }
        following(first: 10) {
          nodes {
            id
            name
            username
            avatar { url width height }
          }
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Recommended - With fragments">

    ```graphql
    fragment UserSummary on User {
      id
      name
      username
      avatar { url }
    }

    query ArticlePage($id: ID!) {
      post(id: $id) {
        id
        title
        author { ...UserSummary }
        lastEditor { ...UserSummary }
        comments(first: 20) {
          nodes {
            id
            body
            author { ...UserSummary }
          }
        }
      }
      me {
        ...UserSummary
        followers(first: 10) { nodes { ...UserSummary } }
        following(first: 10) { nodes { ...UserSummary } }
      }
    }
    ```
      </TabsItem>
    </Tabs>

- Instead of relying on long and complex variable filters, use pagination to handle large data sets.

  For example: Instead of a query like this:

    <Tabs panelHeight={300}>
      <TabsItem label="Before-Query">

    ```graphql
    query BulkPosts($ids: [ID!]!) {
      posts(where: { id_in: $ids }, first: 5000) {
        nodes {
          id
          title
          excerpt
          author { id name }
          comments(first: 500) { nodes { id body author { id name } } }
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Before-Variables">

    ```json
    {
      "ids": [
        "post_000001", "post_000002", "post_000003", "post_000004", "post_000005",
        "... thousands more ids ...",
        "post_004999", "post_005000"
      ]
      // ≈ hundreds of kilobytes, just for variables → likely 413 (Payload Too Large)
    }
    ```

      </TabsItem>
    </Tabs>

    You can split it into:

    <Tabs panelHeight={310}>
      <TabsItem label="Query 1">

    ```graphql
    # Request 1 ≈ a few bytes; repeat with {"after": "<endCursor>"} until hasNextPage=false
    query PagedPosts($first: Int! = 50, $after: String) {
      posts(first: $first, after: $after) {
        nodes {
          id
          title
          excerpt
          author { id name }
        }
        pageInfo { endCursor hasNextPage }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Query 1-Variables">

    ```json
    { "first": 50, "after": null }
    ```

      </TabsItem>
    </Tabs>

    <Tabs panelHeight={280}>
      <TabsItem label="Query 2">

    ```
    # Request N ≈ Still tiny; fetch next pages on demand
    # Only when a user opens a post, also paginated
    query PagedComments($postId: ID!, $first: Int! = 25, $after: String) {
      post(id: $postId) {
        id
        comments(first: $first, after: $after) {
          nodes { id body author { id name } }
          pageInfo { endCursor hasNextPage }
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Query 2-Variables">

    ```json
    { "postId": "post_000123", "first": 25, "after": null }
    ```

      </TabsItem>
    </Tabs>

    <Tabs panelHeight={180}>
      <TabsItem label="Query 3">

    ```graphql
    # If you must target specific IDs, batch them.
    query BatchByIds($ids: [ID!]!) {
      posts(where: { id_in: $ids }) {
        nodes { id title excerpt }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Query 3-Variables">

    ```json
    { "ids": ["post_000001", "... up to ~100 per batch ..."] }
    // Send multiple small requests instead of one huge list
    ```

      </TabsItem>
    </Tabs>

We recommend that you do not:
- Fetch unnecessary fields in your queries.
- Create overly complex nested queries.
- Ignore limit violation errors without addressing root causes.

## Requests per second

The number of uncached requests you can send to the Content API per second. A single request can contain multiple queries and mutations. When you exceed this limit, you'll get a [`429 error`](/docs/api-reference/basics/errors#429-too-many-requests).

<Alert theme="info">

This limit measures how many **requests start per second**. It is different from **concurrency operations**, which is measured by the number of operations running at the same time.

</Alert>

| Plan  | Limit                   |
| ----- | ----------------------- |
| Hobby | 5 req/sec               |
| Growth | 25 req/sec             |
| Enterprise | Up to 500 req/sec  |

## Concurrent operations

The number of uncached GraphQL operations (queries / mutations) that run simultaneously per environment. Multiple operations bundled in a single request count toward the concurrency limit. This helps prevent resource exhaustion during traffic spikes. When you exceed this limit, you'll get a [`429 error`](/docs/api-reference/basics/errors#429-too-many-requests).

<Alert theme="info"> This limit measures **in-flight queries and mutations**. Even if your requests per second (RPS) rate is low, you can still exceed concurrency if many operations run at once. </Alert>

| Plan  | Limit per environment                  |
| ----- | ---------------------- |
| Hobby | <ul><li>Queries: 10</li><li>Mutations: 5</li></ul>|
| Growth | <ul><li>Queries: 30</li><li>Mutations: 10</li></ul>|
| Enterprise | <ul><li>Queries: 60</li><li>Mutations: 20</li></ul> |

To stay below the limit, count the total number of queries and mutations sent simultaneously, not just the number of fired requests. If a request contains five queries, it counts as five concurrent queries.
You can also measure the total in-flight operations at any moment, by using a counter or concurrency control library in your script or code.

We recommend that you:
- Implement proper retry logic with [exponential backoff](#exponential-backoff) to handle temporary errors.
- Distribute requests over time rather than sending large bursts at once.
- Apply connection pooling and request queuing to manage load efficiently.
- Monitor your application's concurrent request patterns.

We recommend that you do not:
- Retry immediately after receiving a 429 error.
- Send large batches of requests simultaneously.
- Ignore concurrent limit violations in your error handling.

## Requests per second vs. Concurrent operations

These two limits measure different things:
- Requests per second (RPS): How many new requests you start each second.
- Concurrent operations: How many queries or mutations are running at the same time, even if they came from the same request.

It’s possible to stay within one limit while exceeding the other. Always design your queries and requests to remain under both the RPS and concurrency limits.

| Scenario | Request per second | Concurrent operations | Result|
| ----- | ---------------------- |--------------- | -----------|
|20 requests per second, each finishes in ~50 ms| <ul><li>RPS = 20</li><li>Within Growth plan limit.</li></ul>  | <ul><li>Concurrency ≈ 1 at any time, since requests complete quickly.</li><li>Within Growth plan limit.</li></ul>  | Both within limits.|
|5 requests per second, each contains 10 queries. Each query takes ~2 seconds to finish.| <ul><li>RPS = 5</li><li>Within Growth plan limit.</li></ul> | <ul><li>Concurrency = 50 (5 requests × 10 queries still running)</li><li>Exceeds Growth plan limit.</li></ul> | Exceeds concurrency limit.|
|40 requests sent at once, each with 1 query.| <ul><li>RPS = 40</li><li>Exceeds Growth plan limit.</li></ul>| <ul><li>Concurrency = 40</li><li>Exceeds Growth plan limit.</li></ul> | Exceeds both limits.|

## Handling API rate limits

In this section, learn how to handle API rate limits with **Next.js**, **Gatsby**, and **Nuxt**.

### Next.js

#### Thread limiting

You can use this experimental setting in **Next.js** for disabling multithreading:

```js
// Your Next.js config file (next.config.js)
...
experimental: {
  workerThreads: false,
  cpus: 1
},
...
```

This setting will force the build to be single-threaded, which limits the speed at which requests are made within the `getStaticProps`.

As a result, the build runs slower but completes without errors.

#### Throttling

The following **Next.js** example uses `pThrottle`, and allows you to control the limit of API calls per interval.

```js
import React from 'react';
import { allProducts } from '../../utils/getProducts';
import { gql } from '../../utils/hygraph-client';
import { throttledFetch } from '../../utils/throttle';

// Singular query used in getStaticProps
const query = gql`
  query GetSingleItem($slug: String!) {
    product(where: { slug: $slug }) {
      name
      slug
    }
  }
`;
export async function getStaticPaths() {
  // One call to get all paths
  // No need to throttle this
  // Unless you have a LOT of these calls
  const products = await allProducts();
  const paths = products.map((product) => ({
    params: { slug: product?.slug },
  }));
  return { paths, fallback: false };
}

export async function getStaticProps({ params }) {
  // For each path, there will be an API call
  // We need to throttle this
  // We need to throttle it on a global throttle, so we need to set that externally

  // throttleFetch comes from a utility area and is shared among all dynamic route files
  /*
    import pThrottle from 'p-throttle'
    import hygraphClient from './hygraph-client'

    // Set the limit of # of calls per interval in ms (5 per second)
    const throttle = pThrottle({limit: 5, interval: 1000})
    export const throttledFetch = throttle(async (...args) => {
        const [query, vars] = args

        const data = await hygraphClient.request(query, vars)

        return data
    })
  */
  const product = await throttledFetch(query, { slug: params.slug });
  return {
    props: product,
  };
}

export default function Page({ product }) {
  // Each page produced by paths and props
  return (
    <>
      <h1>{product.name}</h1>
    </>
  );
}
```

#### Exponential backoff

Combining query execution with exponential backoff retries ensures applications remain reliable, even when encountering concurrent operation limits.

1. The `graphqlFetchWithRetry` function provides error handling and a retry strategy with exponential backoff, ensuring that errors such as concurrent operation limits or temporary rate limiting are retried effectively.

    ```js
    // lib/graphql.ts
    type GraphQLRequest = {
      endpoint: string;
      token?: string;
      query: string;
      variables?: Record<string, unknown>;
      maxRetries?: number;
      baseDelayMs?: number; // starting delay (e.g., 250ms)
      maxDelayMs?: number;  // cap delay (e.g., 5000ms)
      signal?: AbortSignal;
    };

    type GraphQLResponse<T> = {
      data?: T;
      errors?: Array<{ message: string; [key: string]: unknown }>;
    };

    function sleep(ms: number, signal?: AbortSignal): Promise<void> {
      return new Promise((resolve, reject) => {
        if (signal?.aborted) return reject(new DOMException('Aborted', 'AbortError'));
        const timer = setTimeout(resolve, ms);
        signal?.addEventListener('abort', () => {
          clearTimeout(timer);
          reject(new DOMException('Aborted', 'AbortError'));
        });
      });
    }

    // Exponential backoff with jitter and a hard minimum of 1000ms per retry.
    function computeBackoffMs(
      attempt: number,
      baseDelayMs: number,
      maxDelayMs: number,
      minimumMs = 1000
    ): number {
      const exp = Math.max(minimumMs, baseDelayMs * Math.pow(2, attempt));
      const jitter = Math.floor(Math.random() * Math.min(250, exp));
      return Math.min(exp + jitter, maxDelayMs);
    }

    function containsConcurrencyError(errors?: Array<{ message: string }>): boolean {
      if (!errors) return false;
      return errors.some(
        (e) =>
          typeof e.message === 'string' &&
          e.message.toLowerCase().includes('concurrent operations limit exceeded')
      );
    }

    export async function graphqlFetchWithRetry<T = unknown>({
      endpoint,
      token,
      query,
      variables,
      maxRetries = 5,
      baseDelayMs = 250,
      maxDelayMs = 5000,
      signal,
    }: GraphQLRequest): Promise<T> {
      let lastError: unknown;

      for (let attempt = 0; attempt <= maxRetries; attempt++) {
        try {
          const res = await fetch(endpoint, {
            method: 'POST',
            headers: {
              'content-type': 'application/json',
              ...(token ? { authorization: `Bearer ${token}` } : {}),
            },
            body: JSON.stringify({ query, variables }),
            signal,
            cache: 'no-store',
          });

          const is429 = res.status === 429;

          if (res.ok) {
            const json = (await res.json()) as GraphQLResponse<T>;
            const concurrencyHit = containsConcurrencyError(json.errors);

            if (!concurrencyHit) {
              if (json.errors) {
                const messages = json.errors.map((e) => e.message).join('; ');
                throw new Error(`GraphQL error: ${messages}`);
              }
              return json.data as T;
            }

            // Concurrency limit via GraphQL errors – backoff and retry
            if (attempt < maxRetries) {
              const delay = computeBackoffMs(attempt, baseDelayMs, maxDelayMs, 1000);
              await sleep(delay, signal);
              continue;
            }

            throw new Error('Exceeded retries due to concurrent operations limit.');
          }

          // HTTP 429 – backoff and retry (minimum 1s)
          if (is429 && attempt < maxRetries) {
            const delay = computeBackoffMs(attempt, baseDelayMs, maxDelayMs, 1000);
            await sleep(delay, signal);
            continue;
          }

          // Other non-OK statuses – surface
          const body = await res.text().catch(() => '');
          throw new Error(`HTTP ${res.status}: ${body || res.statusText}`);
        } catch (err) {
          lastError = err;
          const isAbort = err instanceof DOMException && err.name === 'AbortError';
          if (isAbort) throw err;

          if (attempt < maxRetries) {
            // Network or transient error – backoff with at least 1s
            const delay = computeBackoffMs(attempt, baseDelayMs, maxDelayMs, 1000);
            await sleep(delay, signal);
            continue;
          }
          break;
        }
      }

      throw lastError instanceof Error ? lastError : new Error('Request failed.');
    }
    ```

2. This example demonstrates how to execute a GraphQL query using the `graphqlFetchWithRetry` function defined in the previous step.

    ```
    // app/api/products/route.ts
    import { NextResponse } from 'next/server';
    import { graphqlFetchWithRetry } from '@/lib/graphql';

    const GRAPHQL_ENDPOINT = process.env.GRAPHQL_ENDPOINT!;
    const GRAPHQL_TOKEN = process.env.GRAPHQL_TOKEN!; // Store server-side only

    export async function GET() {
      try {
        const query = `
          query Products($first: Int!) {
            products(first: $first) {
              id
              name
            }
          }
        `;

        const data = await graphqlFetchWithRetry<{
          products: Array<{ id: string; name: string }>;
        }>({
          endpoint: GRAPHQL_ENDPOINT,
          token: GRAPHQL_TOKEN,
          query,
          variables: { first: 10 },
          maxRetries: 5,
          baseDelayMs: 300,
          maxDelayMs: 5000,
        });

        return NextResponse.json({ ok: true, data });
      } catch (error) {
        return NextResponse.json(
          { ok: false, message: (error as Error).message },
          { status: 429 }
        );
      }
    }
    ```

### Gatsby

#### Concurrency override

You can use `queryConcurrency` with our official <Link href="https://github.com/hygraph/gatsby-source-graphcms#options" target="_blank">Gatsby source plugin for Hygraph projects</Link>.

This key indicates the number of promises ran at once when executing queries. Its default value is set to 10.

<Alert theme="warning">
This plugin has been deprecated and no longer receives support. However, if you are already using it and have encountered a problem with rate limits, then we suggest you use the `queryConcurrency` solution.
</Alert>

#### Throttling

The following **Gatsby** example uses `pThrottle`, and allows you to fetch 1 concurrent request maximum, with a minimum delay of 0.5 seconds.

```js
import { createHttpLink } from "apollo-link-http";
 import pThrottle from "p-throttle";
// Throttle fetches to max 1 concurrent request and
  //  min. delay of 0.5 seconds.
const throttledFetch = pThrottle( (...args) => {
    return fetch(...args);
  }, 1, 500);
const link = createHttpLink({ uri: "/graphql" fetch: throttledFetch });
```

### Nuxt

#### Thread limiting

You can add the following to your `nuxt.config.js` to avoid getting a [429 error](/docs/api-reference/basics/errors#429-too-many-requests). It will stop GraphQL requests from overloading Hygraph's API limits when building.

```js
// Your Nuxt config file (nuxt.config.js)
generate: {
concurrency: 250, //maximum number of requests per thread. This will only build 250 at a time based on the api rate limit
interval: 200, //delay by 0.2s. You can adjust this to be higher if you still run into issues
},
```


---
# API Playground

Source: https://hygraph.com/docs/api-reference/basics/api-playground

The API playground is a great way to experiment with querying, and mutating data. You can find the API Playground from the sidebar once logged into your project.

![API Playground](/images/docs/api-reference/basics/playground.png)

When you first open the API Playground, you will see some initial comments introducing GraphQL, followed by a query based on the model you have in your project. If the project has more than one model, the sample query will be provided using the first one.

Under the demo query you will find some additional comments on keyboard shortcuts.

The API Playground is also great for:

- Testing authorization and access control with API keys.
- Working with, and testing multiple environments.
- Working with, and testing localized content.
- Explore previously ran queries, and mutations.
- Run previous queries in a single click
- Explore queries, mutations, arguments, and more with explorer view.
- Browse auto-generated schema documentation
- Work with variables, and named queries

Each tab of the API playground has four buttons:

- **Prettify:** Cleans up the format and indentation of your typed query.
- **Environment:** Allows you to select one of your configured environments, as well as the Management API.
- **Stage:** Allows you to select one of your configured stages.
- **Locale:** Allows you to select one of your configured locales. If you select `No Locale`, it will fetch all the content.

By Default, the API Playground explorer located to the left of the screen will have the items of the demo query selected. You can modify the query manually, or use the checkboxes to do it instead.

You can also add a new query by clicking on the **+** button next to the query tabs.

You can find all your queries in the `My Queries` tab, located next to the `Explorer` tab. There, you can select which of your queries you wish to display, and edit the name by clicking on the pencil icon.

At the bottom of the screen you will find two sections: Query variables, and HTTP headers. In the **Query variables** section you can provide the variables, if necessary for your query to work. If you're working with GraphQL APIs that require you to pass custom headers, you can do that in the **HTTP headers** section.


---
# Authorization

Source: https://hygraph.com/docs/api-reference/basics/authorization

By default, queries and mutations require a [Permanent Auth Token](#permanent-auth-tokens), but you can configure the [Public API Permissions](#public-api-permissions) to allow unauthenticated requests.

Hygraph allows you to configure access for each model, stage, environment, locale, and whether or not you permit mutations.

## Public API permissions

By default, all new projects disable public API access.

<Alert theme="warning">
Enabling public access to your project means that anybody with your API endpoint can query sensitive data, and perform destructive actions if configured incorrectly.
</Alert>

You can configure custom permissions, or initialize the defaults.

For example, here you can see how to configure the Content API to allow access to READ the `Page` model on stages `Published` and `Draft` with the locale `English`.

![Create API permission](/images/docs/api-reference/basics/create-permission.png)

You can also specify an optional condition that restricts access even further. For example, you could specify the condition `{ "id": "ckoimwlu80ck20a88z6i754cw" }`. This would then only allow you to fetch the `Page` with `id` `ckoimwlu80ck20a88z6i754cw`.

[Learn more about Public API permissions](/docs/getting-started/access-and-permissions/content-api-permissions#set-up-public-api-access)

### Default public stage

If no stage parameter is set on the GraphQL query, or via an [HTTP header](/docs/api-reference/content-api/headers), the content from the default set content stage will be served.

![Default Content Stage](/images/docs/api-reference/basics/default-content-stage.png)

The default public stage is set to `PUBLISHED` for all new projects.

## Permanent auth tokens

Permanent Auth Tokens are used for controlling access to querying, mutating content, and come in the form of Bearer token authentication.

Similar to Public API permissions, you can create individual PATs for specific API actions.

Some users create PATs for only querying data from the draft stage, for creating previews in staging environments. You may also opt to create a PAT for mutations, so you can perform changes to your content models server-side.

If you are mutating data from the frontend, you should hide this token at the server level, and not expose your PAT client-side.

The Permanent Auth Token must be passed via the `Authorization` header on HTTP requests in the format of a Bearer token:

```
Authorization: Bearer PERMANENT_AUTH_TOKEN
```

[Learn more about PAT permissions](/docs/getting-started/access-and-permissions/content-api-permissions#set-up-a-pat-with-model-specific-permissions)

## Third-party authentication

With third-party app authentication support, you can enable Hygraph users to connect their Hygraph accounts to your application, and execute Content API and Management API requests.

Permanent Auth Tokens are non-personal tokens. With PATs, you cannot attribute an API request to any specific user. With third-party authentication, you can control access within your applications based on roles and permissions configured in Hygraph, and then attribute any Hygraph mutation from your application to the user who initiated it. This is helpful in tracking content changes in visual builder applications, or activities in workflow integration apps, such as Jira, Slack, and so on. You can now link different activities performed by the same user, thus enhancing visibility and auditability.

### Authenticate Management API requests

When you request tokens from Auth0 for Management API access, omit the `audience` parameter. Auth0 then returns both an `access_token` and an `id_token`. For Hygraph Management API requests, use the `id_token`, not the `access_token`.

The `id_token` is associated with the authenticated user. The Management API uses Hygraph's [roles and permissions system](/docs/getting-started/access-and-permissions/user-roles-and-permissions), so requests made with that token are allowed or denied according to the permissions granted to that user within the project.

To verify this, try querying the Management API with the `id_token`, including running a mutation. If the project has [audit logs](/docs/developer-guides/project/audit-logs) enabled, the corresponding entry should show that the action was performed by the authenticated user.

### Set up third-party connections

1. Before you set up third-party authentication, you need an OAuth `client ID` and `client secret` from Hygraph. Contact our Support team, and provide the following details of your application:

    - Name
    - Description
    - Logo
    - Type - Single page application or native application
    - Home page link
    - Allowed callback URLs (Allowed URLs for redirecting users after login)
    - Allowed logout URLs (Allowed URLs for redirecting users after logout)
    - Allowed Web Origins (List of URLs from where an authorization request can originate)

    After Hygraph approves your application, you receive an OAuth `client ID` and `client secret`. Store your client secret securely. If your client secret is compromised, contact Hygraph immediately to <Link href="https://auth0.com/docs/get-started/applications/rotate-client-secret" target="_blank">rotate to a new one</Link> and then update all authorized apps with the new client secret.

2. Update your app with OAuth credentials.

### Manage existing connections

You can view a list of all active third-party connections in your account settings. At the top right of your screen, click your profile name, and then click **Account Settings**. Under **Connected apps**, you can view a list of all third-party apps and services connected to the account. To revoke access to any app, click **Revoke** next to it.

### Examples

The following sections provide examples on setting up third-party authentication for single page and native applications. To learn how to set up authentication for other app types, see <Link href="https://auth0.com/docs/quickstart/spa" target="_blank">Auth0 documentation</Link>.

#### Single page application

1. Clone the <Link href="https://github.com/auth0-samples/auth0-javascript-samples/tree/master/01-Login" target="_blank">sample application</Link> locally.
2. Run `npm install` to install the necessary packages for the sample to run.
3. In the `public/js/app.js` file, add the `auth0Client` section.

    ```javascript
    const configureClient = async () => {
      const response = await fetchAuthConfig();
      const config = await response.json();

      auth0Client = await auth0.createAuth0Client({
        domain: config.domain,
        clientId: config.clientId,
        // ++ add the auth0Client config
        auth0Client: {
          __useTenantInfo: config.isThirdPartyClient,
        },
      });
    };
    ```

4. To specify the application client ID and domain, make a copy of `auth_config.json.example` and rename it to `auth_config.json`. Open the `auth_config.json` file in a text editor and provide the correct values for your application:

    ```json
    {
      "domain": "auth.hygraph.com",
      "clientId": "CLIENT_ID",
      "isThirdPartyClient": true
    }
    ```

5. Run `npm run dev` to start the application.

#### Native application - Slack

This example assumes that you've already built a Slack app in your workspace. If you haven't built a Slack app, follow the instructions <Link href="https://tools.slack.dev/deno-slack-sdk/guides/getting-started/" target="_blank">here</Link>.

1. Define a new OAuth2 provider in the `manifest.ts` file.

    ```typescript
    // Define a new OAuth2 provider
    // Note: replace <your_client_id> with your actual client ID
    const HygraphProvider = DefineOAuth2Provider({
      provider_key: "hygraph",
      provider_type: Schema.providers.oauth2.CUSTOM,
      options: {
        client_id: "<your_client_id>",
        scope: ["openid", "profile", "email", "offline_access"],
        provider_name: "Hygraph",
        authorization_url: "https://graphcms.auth0.com/authorize",
        token_url: "https://graphcms.auth0.com/oauth/token",
        token_url_config: {
          use_basic_auth_scheme: false,
        },
        identity_config: {
          url: "https://graphcms.auth0.com/userinfo",
          account_identifier: "$.sub",
          http_method_type: "GET",
        },
        authorization_url_extras: {
          prompt: "consent",
          access_type: "offline",
          audience: "https://graphcms.auth0.com/api/v2/",
        },
        use_pkce: true,
      },
    });

    export default Manifest({
      // ...
      // Add APIs that your application is going to call
      outgoingDomains: [
        "eu-central-1.api.hygraph.com",
        "management.hygraph.com",
        "api-eu-central-1.hygraph.com",
      ],
      // ...
      // Tell your app about your OAuth2 providers here:
      externalAuthProviders: [HygraphProvider],
    });
    ```

2. Now, build a Slack function that creates a content entry on a user’s behalf.

    ```typescript
    import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";

    export const CreateContentFunctionDefinition = DefineFunction({
      callback_id: "create_content_function",
      title: "Create content function",
      description: "A create content function",
      source_file: "functions/create_content_function.ts",
      input_parameters: {
        properties: {
          token: {
            type: Schema.slack.types.oauth2,
            oauth2_provider_key: "hygraph",
          },
          project_id: {
            type: Schema.slack.types.string,
            description: "The project to create content for",
          },
          model_id: {
            type: Schema.slack.types.string,
            description: "The model to create content for",
          },
          channel_id: {
            type: Schema.slack.types.channel_id,
            description: "The channel to post the message in",
          }
        },
        required: ["token", "project_id", "model_id", "channel_id"],
      },
      output_parameters: {
          properties: {
            contentId: {
              type: Schema.types.string,
              description: "ID of the created content",
            },
          },
          required: ["contentId"],
        },
    });

    export default SlackFunction(
      CreateContentFunctionDefinition,
      async ({ inputs, client }) => {
        // Get the token:
        const tokenResponse = await client.apps.auth.external.get({
          external_token_id: inputs.token,

        });
        if (tokenResponse.error) {
          const error = `Failed to retrieve the external auth token due to ${tokenResponse.error}`;
          return { error };
        }

        // If the token was retrieved successfully, use it:
        const externalToken = tokenResponse.external_token;

        // Make external API call with externalToken
        const response = await fetch(
          "https://eu-central-1.api.hygraph.com/graphql",
          {
            method: "POST",
            body: JSON.stringify({
              query: `query Viewer {
                _viewer {
                    ... on UserViewer {
                        id
                        user {
                            id
                            profile {
                                email
                                name
                            }
                        }
                        project(id: "${inputs.project_id}") {
                          environment(id: "master"){
                              authToken
                          }
                        }
                    }
                }
            }
            `,
            }),
            headers: new Headers({
              Authorization: `Bearer ${externalToken}`,
              "Content-Type": "application/json",
            }),
          }
        );
        if (response.status != 200) {
          const body = await response.text();
          const error = `Failed to call my endpoint! (status: ${response.status}, body: ${body})`;
          return { error };
        }

        const responseBody = await response.json();

        const uuid = crypto.randomUUID();

        const contentApiToken = responseBody.data._viewer.project.environment.authToken;

        const createContentResponse = await fetch(
          "https://api-eu-central-1.hygraph.com/v2/cmaz8u024000b07w2o46szn1y/master",
          {
            method: "POST",
            body: JSON.stringify({
              query: `mutation createContent($data: DemoModel23May20250843CreateInput!) {
                createDemoModel23May20250843(data: $data) {
                  id
                }
              }`,
              variables: {
                data: {
                  title: `Sample Content ${uuid}`,
                  slug: `sampleContent${uuid}s`,
                  // Add other fields as required by your model
                },
              },
            }),
            headers: new Headers({
              Authorization: `Bearer ${contentApiToken}`,
              "Content-Type": "application/json",
            }),
          }
        );

        if (createContentResponse.status != 200) {
          const body = await createContentResponse.text();
          const error = `Failed to create content! (status: ${createContentResponse.status}, body: ${body})`;
          return { error };
        }

        client.chat.postMessage({
          channel: inputs.channel_id,
          text: `Content created successfully with ID: ${uuid}`,
        });

        return { outputs: { contentId: uuid } };
      }
    );
    ```

3. Next, create a Slack workflow.

    ```typescript
    import { DefineWorkflow, Schema } from "deno-slack-sdk/mod.ts";
    import { CreateContentFunction } from "../functions/content/definition.ts";

    const CreateContentWorkflow = DefineWorkflow({
      callback_id: "create_content_workflow",
      title: "Create Content",
      description: "A workflow to create new content",
      input_parameters: {
        properties: {
          interactivity: {
            type: Schema.slack.types.interactivity,
          },
        },
        required: ["interactivity"],
      },
    });

    CreateContentWorkflow.addStep(CreateContentFunction, {
      interactivity: CreateContentWorkflow.inputs.interactivity,
      token: {
        credential_source: "END_USER",
      },
    });

    export default CreateContentWorkflow;
    ```

4. Create a trigger to invoke the custom function for the workflow.

    ```typescript
    import { Trigger } from "deno-slack-sdk/types.ts";
    import { TriggerContextData, TriggerTypes } from "deno-slack-api/mod.ts";
    import CreateContentWorkflow from "../workflows/create_content_workflow.ts";

    const createContentTrigger: Trigger<typeof CreateContentWorkflow.definition> = {
      type: TriggerTypes.Shortcut,
      name: "Create Content trigger",
      description: "Trigger to create new content",
      workflow: `#/workflows/${CreateContentWorkflow.definition.callback_id}`,
      inputs: {
        interactivity: {
          value: TriggerContextData.Shortcut.interactivity,
        },
      },
    };

    export default createContentTrigger;
    ```

5. Add the client secret that you received from Hygraph for the Slack app. This secret is used to initiate the OAuth2 flow.

    ```bash
    slack external-auth add-secret --provider hygraph --secret "<your_client_secret>"
    ```

6. Run the Slack application.

## API endpoints

![API Endpoints](/images/docs/api-reference/basics/api-endpoints.png)

### Regular read & write endpoint

Each Hygraph project you create, or are invited to, has a unique GraphQL API endpoint (per environment). This endpoint permits you to both query and mutate data within your project. You will find it as **Content API** endpoint in your project's **API Access** settings.

GraphQL introspection is enabled by default, so anybody with access to your endpoint can traverse the graph to see your content types, as well as all queries and mutations.

This API endpoint also contains the current schema [environment](/docs/api-reference/basics/environments), by default this will be `master`.

The API endpoint has the following composition:

```
https://[region].hygraph.com/v2/[projectId]/[environment]
```

Click [here](/docs/api-reference/basics/caching#regular-read-and-write-endpoint) to learn more about this endpoint.

### High performance endpoint

This high performance endpoint is ideal for delivering content around the globe with low latency and high read-throughput.

The API endpoint has the following composition:

```
https://[region].cdn.hygraph.com/content/[projectId]/[environment]
```

Click [here](/docs/api-reference/basics/caching#high-performance-endpoint) to learn more about this endpoint.

## Resources

You might find the following documents useful:

- [Permissions](/docs/getting-started/access-and-permissions/content-api-permissions): This document contains information on permissions, how they work, and their limits.
- [Roles and permissions](/docs/getting-started/access-and-permissions/user-roles-and-permissions): This document contains information on how to work with roles and permissions in the Hygraph app.
- [API access](/docs/getting-started/access-and-permissions/api-access): This document covers the API access section of the Hygraph app as well as its subsections: Endpoints, Content API, and Permanent auth tokens.


---
# Caching

Source: https://hygraph.com/docs/api-reference/basics/caching

## Overview

All Content APIs are served via our globally distributed edge cache. Whenever a query is sent to the content API, its response is cached in multiple <Link href="https://www.fastly.com/network-map/" target="_blank">POP</Link> (data centers) around the globe.

![Hygraph CDN Map](/images/docs/api-reference/basics/cdn-map.svg)

<Alert theme="info">
Hygraph handles all cache management for you! For faster queries, use `GET` requests, so browsers can leverage advanced caching abilities available in the headers.
</Alert>

Hygraph comes with two different content API endpoints, served by 2 different CDN providers. To understand which endpoint you should use, look at the following table.

| Endpoint name                 | Endpoint                                                                  | Consistency                            | Access       |
| ----------------------------- | ------------------------------------------------------------------------- | -------------------------------------- | ------------ |
| Regular read & write endpoint | `https://${region}.hygraph.com/v2/`<br/>`${projectId}/${environment}`     | Eventual (Read-after-write within POP) | Read & Write |
| High performance endpoint     | `https://${region}.cdn.hygraph.com/v2/`<br/>`${projectId}/${environment}` | Eventual                               | Read & Write |

<Alert theme="warning">
<b>CDN =</b> Content-Delivery-Network

You can see the endpoints in your project settings <b>(Settings->API Access->Endpoints)</b>.
</Alert>

## Regular read & write endpoint

<Alert theme="warning">

Hygraph Studio does not display this legacy endpoint. 

</Alert>

The **Regular read & write endpoint** allows for reads and writes. All your requests are cached, and any mutation will invalidate the cache for your project.

Even though this endpoint is eventually consistent, within a single region you will get read-after-write consistency.

<Alert theme="warning">
This endpoint can take up to 30s to update all caching nodes worldwide.
</Alert>

This endpoint is ideal for delivering content around the globe with one endpoint, but it only has basic caching logic.

## High performance endpoint

We use a state-of-the-art caching approach, and we have developed a high-performance edge service on the <Link href="https://www.fastly.com/products/edge-compute/serverless" target="_blank">Fastly Compute Edge platform</Link>. The service is deployed <Link href="https://www.fastly.com/network-map/" target="_blank">close</Link> to your users around the world.

<Alert theme="warning">
You will benefit from continual improvements on the cache invalidation logic without any code changes on your part.
</Alert>

This endpoint is ideal for delivering content around the globe with low latency and high read-throughput.

<Alert theme="info">
This endpoint has **model + stage based invalidation**. This means that instead of invalidating the complete cache for content and schema changes, we only invalidate the models that were changed based on the mutations used. The rest will stay cached and, therefore, fast. Click [here](/docs/api-reference/basics/caching#model-stage-based-invalidation) to learn more.

In some cases, entry-based cache invalidation is possible. [Click here to learn more](/docs/api-reference/basics/caching#entry-based-cache-invalidation)
</Alert>

## Consistency

To understand both endpoints better, you should have a basic knowledge of cache consistency modes. You can be sure that any changes have persisted at Hygraph if your response was successful.

### Eventual consistency

Some changes are not visible immediately after the update. For example, if you `create`, `delete` or `update` content the update is distributed around the globe with a short delay. Theoretically, if you read content right after a mutation, you may receive stale content.

### Read-after-write consistency

In contrast, <Link href="https://avikdas.com/2020/04/13/scalability-concepts-read-after-write-consistency.html" target="_blank">read-after-write consistency</Link> guarantees that a subsequent read after an update, delete, or create can see those changes immediately. This is only valid for operations hitting the same POP (point-of-presence).

## Model + stage based invalidation

**Model + stage based invalidation**, which is only available for our [High performance endpoint](/docs/api-reference/basics/caching#smart-cache-invalidation), allows invalidating only the models that were changed based on the mutations used for content and schema changes, rather than invalidate the complete cache.

Regarding queries that fetch related content that needs to be invalidated: We analyze query responses and invalidate only the cached queries that contain the changed model.

For example:

<Tabs panelHeight={230}>
<TabsItem label="Query">
```graphql
{
	posts {
    title
    author {
      id
    }
  }
}
```
</TabsItem>
<TabsItem label="Response">
```graphql
{
  "data": {
    "posts": [
      {
        "title": "Post",
        "author": {
          "name": "Fabian"
        }
      }
    ]
  }
}
```
</TabsItem>
</Tabs>

Considering invalidation after a **schema change**, if a user were to update the `Author` model shown in the example above, this cached query would be invalidated, as it also returned the `Author` model.

For **content changes**, we also take the stage into account, meaning that updating an `Author` entry, and not publishing it, would invalidate all cached queries that returned the `DRAFT` stage and the `Author` model. Queries that returned the `PUBLISHED` stage will remain cached.

## Smart cache invalidation

Our System understands if mutations are flowing through the cache and invalidates the affected resources with an eventual consistency guarantee.

## Entry-based cache invalidation

In some cases, cache invalidation can be done on an entry basis.

<Alert theme="warning">
- Caching of content of different stages remains independent.
- Mutation of content in the `DRAFT` stage won't invalidate content in the `PUBLISHED` stage.
</Alert>

There are three scenarios where entry-level tagging is applied and invalidation becomes more granular, targeting only responses embedding specific entries:

- [Query of a single entry by `id`](/docs/api-reference/basics/caching#query-of-a-single-entry-by-id)
- [Single reference fields](/docs/api-reference/basics/caching#single-reference-fields)
- [Query of multiple models with a `where` argument involving only unique fields](/docs/api-reference/basics/caching#multi-model-query-with-unique-fields-only) (like a slug)

<Alert theme="info" title="Example situation">
We'll use the following example situation to explain the three possible cases:

![entry-based-caching](/images/docs/api-reference/basics/entry-based-caching.png)

Let's consider the schema above. It represents a mock of a recipe website presenting image descriptions and preparation steps of the various dishes. Each recipe is also linked with a chef who created it.

The GraphQL snippets in the following examples use the flag `[EBC]` to identify invalidation scenarios that work at entry level.
</Alert>

### Query of a single entry by `id`

Following our recipe website example situation, in this scenario we query a single recipe (entry). When that recipe is found, the cached response for the query is only invalidated if there are mutations sent that affect this specific entry.

The cached response will remain valid after mutations targeting other recipes, or any other model.

```graphql
# Invalidated on
# - changes to Recipe 'cltx865t89nu607uj4tvaact5' [EBC]
query {
  recipe(where: {
    id: "cltx865t89nu607uj4tvaact5"
  }){
    id
    title
    description
  }
}

```

### Single reference fields

In this scenario and following our example situation, the query targets multiple recipes along with their associated chefs.

Here, the cache mechanism becomes a little more complex as it has to deal with multiple relationships:

```graphql
# Invalidated on:
# - changes or creation of any Recipe
# - changes of specific Chef related to the returned recipes [EBC]
query {
  recipes(first: 5) {
    chef { #single reference field
      id
      name
      bio
    }
  }
}
```

Changing any of the recipes or adding new recipes, will invalidate the cache associated with this query.

This is because the query fetches the first five recipes, and any changes or additions could potentially alter this result.

Additionally, any changes to the specific chefs who are directly associated with the returned recipes will also invalidate the cache. Other chefs' information will not affect the response and so it does not invalidate the cache.

The EBC behavior from the previous snippet does not apply if chef parameters are part of the query `where` argument:

```graphql
# Invalidated on:
# - changes or creation of any Recipe
# - changes or creation of any Chef
query {
  recipes(where: {
    chef: {
      birthdate_gt: "1990-04-05T00:00:00Z"
    }
  }) {
    chef {
      id
      name
      bio
    }
  }
}
```

Since the chef's `birthdate` is now a determining factor in the query results, any changes or additions to the chefs - regardless of their association with the returned recipes - can potentially alter the result of this query. For example, the birthday of another chef is updated and becomes included by the filter.

Because of this, even modifying or adding chefs not directly associated with the returned recipes invalidates the cache.

#### Nested references

Entry-based cache invalidation also applies when the reference fields are nested deeply in the query tree, even if they are children of multi reference fields.

```graphql
# Invalidated on:
# - changes or creation of any Chef
# - changes or creation of any Recipe
# - changes of specific RecipeWalkthrough related to
#   the returned recipes [EBC]
# - changes of specific Asset(video) related to
#   the returned RecipeWalkthrough [EBC] 
query {
  chefs { # multi model query
    name
    recipes {  # multi reference field
      recipeWalkthrough { # single reference field
        video { # single reference field
          fileName
          url
        }
      }
    }
  }
}
```

In this scenario, where the query involves multiple models and their relationships, the cache invalidation becomes a bit complex.

Following our recipe website schema example: Any changes or additions to the chefs, recipes, or recipe walkthroughs, will invalidate the cache associated with this query. Additionally, any changes or additions to the specific assets (videos) related to the returned recipe walkthroughs will invalidate the cache as well.

Modifying or adding assets not directly associated with the returned recipe walkthroughs does not affect the cache, so it will remain valid.

### Multi-model query with unique fields only

<Alert theme="warning">
This will only work for non-localized unique fields.
</Alert>

In the following example, we are querying for a single recipe based on a unique field - the slug:

```graphql
# Invalidated on:
# - changes of specific `Recipe` with slug "classic-spaghetti-carbonara"
query {
  recipe(where:{ slug: "classic-spaghetti-carbonara"}) {
    id
    slug
    title
    description
    createdAt
  }
}
```

The cache will be invalidated only if there are changes to the specific recipe with the slug *"classic-spaghetti-carbonara"*.

Any changes to other recipes will not affect the cache associated with this query.

In this other example, the query fetches chefs and the recipes associated with each chef based on a unique field - the slug:

```graphql
# Invalidated on:
# - changes or creation of any Chef
# - changes of specific `Recipe` with slug "classic-spaghetti-carbonara"
query {
  chefs {
    id
    name
    recipes(where: {slug: "classic-spaghetti-carbonara"}) {
      id
      title
      description
    }
  }
}
```

The cache will be invalidated if there are changes to the specific recipe with the slug "classic-spaghetti-carbonara" or any changes or additions to the chefs.

Any changes to other recipes not having the slug "classic-spaghetti-carbonara" will not affect the cache associated with this query.

## stale-if-error

In case of an outage of our APIs - this includes remote field origin errors as well- we will fall back for at least 24h to the latest cached content on our edge servers. This adds an additional reliability layer.

<Alert theme="info" title="Pro Tip">
This is only available on the <b>High performance</b> endpoint.

The default `Stale-if-error` for all shared clusters is 86400s (1 day).
</Alert>

You can use a header for the **High performance endpoint** that lets you set `stale-if-error` on a per query basis.

```graphql
{
  "hyg-stale-if-error": "21600"
}
```

The values are in seconds.

## stale-while-revalidate

With the **High performance endpoint** you will get cached responses directly, while we update the content in the background. This means your content is always served on the edge, with low latency for your users.

_Staleness_ refers to how long we deliver stale data while we revalidate the cache in the background if the cache was invalidated.

<Alert theme="info" title="Pro Tip">
This is only available on the <b>High performance</b> endpoint.

The default `stale-while-revalidate` for our shared clusters is `0`.
</Alert>

You can use a header for the **High performance endpoint** that lets you set `stale-while-revalidate` on a per query basis.

```graphql
{
  "hyg-stale-while-revalidate": "27"
}
```

The values are in seconds.

## Remote fields

GraphQL queries that contain remote fields are cached differently. By default, a response is marked as cacheable when all remote field responses are cacheable according to <Link href="https://datatracker.ietf.org/doc/rfc7234/" target="_blank">rfc7234</Link>. You can control the TTL (Time-to-Live) cache by returning the `Cache-Control` response header.

By default, we will set a TTL of `900s`, you can set a minimum TTL of `60s`. While it is also possible to respond with a `no-store` cache directive to disable the cache, this is not recommended, as it marks the entire response as not cacheable and will increase the load on your origin.


---
# Content Freeze API reference

Source: https://hygraph.com/docs/api-reference/basics/content-freeze

A content freeze pauses content creation, editing, and publishing across an environment or an entire project, while schema changes are promoted. This reference covers the `contentFreezes` query and the `setContentFreeze` and `liftContentFreeze` mutations, so you can read, start, and lift a freeze directly through the Management API.

For information on configuring a freeze from Studio and what editors see while one is active, see [Content Freeze](/docs/developer-guides/project/content-freeze).

## Authentication

Use a Permanent Auth Token or App Token with the **Management API**.

- **`contentFreezes`**: Any project member can read freeze history.
- **`setContentFreeze`** and **`liftContentFreeze`**: Require the **Allows starting, scheduling, and lifting content freezes** permission. The Admin role includes it by default; you can also grant it on custom roles or PATs.

## Retrieve content freeze

Returns every content freeze for the project, past and present, unless you filter the list. Run the `contentFreezes` query on `project`.

<Dl>
    <Dt>Parameters</Dt>
    <Dd>
        | Argument | Type | Default | Description |
        |---|---|---|---|
        | `filter` | `ContentFreezeFilter` | `ALL` | Pass `OPEN` to return only freezes that haven't ended yet. |

        `contentFreezes` doesn't take pagination arguments. It returns the full list for the project on every call. It also doesn't filter by environment. If you need freezes for a specific environment, filter the returned list on the `environment` field.
    </Dd>
    <Dt>Fields</Dt>
    <Dd>
        | Field | Type | Description |
        |---|---|---|
        | `id` | `ID!` | Unique identifier for the freeze. |
        | `createdAt` | `DateTime!` | When the freeze record was created. |
        | `updatedAt` | `DateTime!` | When the freeze record last changed. |
        | `environment` | `Environment` | The environment this freeze applies to. Null for a project-wide freeze. |
        | `startAt` | `DateTime!` | When the freeze begins. |
        | `endAt` | `DateTime` | When the freeze ends. `null` for an open-ended freeze (no scheduled end). Set to a future time when you schedule an end, or to the current time when the freeze is lifted early. |
        | `message` | `String` | Announcement message shown to editors. Null if none was set. |
        | `setBy` | `CreatedBy` | Who started the freeze: a project member, Permanent Auth Token, or App Token. |
        | `liftedBy` | `CreatedBy` | Who ended the freeze early: a project member, Permanent Auth Token, or App Token. `null` if it reached its scheduled end. |
    </Dd>
</Dl>

### Example query

<Tabs>
  <TabsItem label="Query">

```graphql
query ContentFreezeQuery {
  viewer {
    project(id: "your-project-id") {
      contentFreezes(filter: OPEN) {
        id
        environment {
          name
        }
        startAt
        endAt
        message
        setBy {
          ... on Member {
            profile {
              name
            }
          }
        }
        liftedBy {
          ... on Member {
            id
            profile {
              name
            }
          }
        }
      }
    }
  }
}
```
  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "viewer": {
      "project": {
        "contentFreezes": [
          {
            "id": "fdacc0e66e044724bca5aca736ade52e",
            "environment": {
              "name": "master"
            },
            "startAt": "2026-07-15T22:00:00.000Z",
            "endAt": "2026-07-22T22:00:00.000Z",
            "message": null,
            "setBy": {
              "profile": {
                "name": "Admin User"
              }
            },
            "liftedBy": null
          }
        ]
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Set content freeze

Use the `setContentFreeze` mutation to start a freeze or reschedule the current freeze. Requires the **Allows starting, scheduling, and lifting content freezes** permission.

<Dl>
    <Dt>Parameters</Dt>
    <Dd>
        | Argument | Type | Required | Description |
        |---|---|---|---|
        | `data.projectId` | `ID!` | Yes | The project to freeze. |
        | `data.environmentId` | `ID` | No | Target environment. Omit for a project-wide freeze. |
        | `data.startAt` | `DateTime` | No | When the freeze begins. Omit to start immediately. |
        | `data.endAt` | `DateTime` | No | When the freeze ends. Omit for an open-ended freeze. |
        | `data.message` | `String` | No | Announcement message shown to editors. |

        Each call applies to a single scope, either one environment or the whole project. To freeze multiple environments, call `setContentFreeze` once per environment ID. Calling it again for the same scope ends any open freeze for that scope and creates a new one.

        `startAt` and `endAt` must not be in the past. If you set `endAt`, it must not be before `startAt`.
    </Dd>
    <Dt>Returns</Dt>
    <Dd>
        `ContentFreezePayload`, containing `project`. Query `contentFreezes` to confirm the resulting freeze.
    </Dd>
</Dl>


### Examples

- **Set a project-wide freeze, starting immediately, with no end date:**

    <Tabs>
      <TabsItem label="Mutation">

    ```graphql
    mutation SetProjectWideContentFreeze {
      setContentFreeze(data: { projectId: "your-project-id" }) {
        project {
          id
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Response">

    ```json
    {
      "data": {
        "setContentFreeze": {
          "project": {
            "id": "your-project-id"
          }
        }
      }
    }
    ```

      </TabsItem>
    </Tabs>

- **Set a freeze scoped to one environment, with a message:**

    <Tabs>
      <TabsItem label="Mutation">

    ```graphql
    mutation SetEnvironmentContentFreeze {
      setContentFreeze(
        data: {
          projectId: "your-project-id"
          environmentId: "your-environment-id"
          message: "Freezing content while we promote schema changes."
        }
      ) {
        project {
          id
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Response">

    ```json
    {
      "data": {
        "setContentFreeze": {
          "project": {
            "id": "your-project-id"
          }
        }
      }
    }
    ```

      </TabsItem>
    </Tabs>

## Lift content freeze

Use the `liftContentFreeze` mutation to end the current freeze for a scope before its scheduled end. Requires the **Allows starting, scheduling, and lifting content freezes** permission.

<Dl>
    <Dt>Parameters</Dt>
    <Dd>
        | Argument | Type | Required | Description |
        |---|---|---|---|
        | `data.projectId` | `ID!` | Yes | The project whose freeze you're lifting. |
        | `data.environmentId` | `ID` | No | Target environment. Omit to lift a project-wide freeze. |

        Lifting a freeze sets its `endAt` to the current time. The record isn't deleted; it remains queryable through `contentFreezes` as a record.
    </Dd>

    <Dt>Returns</Dt>
    <Dd>
        `ContentFreezePayload`, containing `project`. Query `contentFreezes` to confirm the freeze ended.
    </Dd>
</Dl>

### Examples

- **Lift a project-wide freeze:**

    <Tabs>
      <TabsItem label="Mutation">

        ```graphql
        mutation LiftProjectWideContentFreeze {
          liftContentFreeze(data: { projectId: "your-project-id" }) {
            project {
              id
            }
          }
        }
        ```

          </TabsItem>
          <TabsItem label="Response">

        ```json
        {
          "data": {
            "liftContentFreeze": {
              "project": {
                "id": "your-project-id"
              }
            }
          }
        }
        ```

      </TabsItem>
    </Tabs>

- **Lift an environment-scoped freeze:**

    <Tabs>
      <TabsItem label="Query">

    ```graphql
    mutation LiftEnvironmentContentFreeze {
      liftContentFreeze(
        data: {
          projectId: "your-project-id"
          environmentId: "your-environment-id"
        }
      ) {
        project {
          id
        }
      }
    }
    ```

      </TabsItem>
      <TabsItem label="Response">

    ```json
    {
      "data": {
        "liftContentFreeze": {
          "project": {
            "id": "your-project-id"
          }
        }
      }
    }
    ```

      </TabsItem>
    </Tabs>

## Related docs

- [Content Freeze](/docs/developer-guides/project/content-freeze): Learn what a content freeze does and how to configure it from Studio.
- [Environments](/docs/api-reference/basics/environments): Create and manage the environments a freeze can target.
- [Management API permissions](/docs/developer-guides/project/management-api-permissions): Confirm who holds the **Allows starting, scheduling, and lifting content freezes** permission.

---
# Environments

Source: https://hygraph.com/docs/api-reference/basics/environments

## Overview

Safely work on isolated instances of your project with environments. Environments are for making changes to your GraphQL schema, and testing out new content types without breaking your production implementation, not to be used for editorial workflows.

Depending on your current user role, and payment plan, you can manage your environments from your project settings.

[Learn more about working with multiple environments](/docs/developer-guides/project/multiple-environments)

## Create environments

You can create environments using our UI by following [these steps](/docs/developer-guides/project/manage-project-environments#create-an-environment).

## Switching environments

You can switch environments using our UI by following [these steps](/docs/developer-guides/project/manage-project-environments#switch-environments).

## Environment endpoints

Each environment has its own API endpoint, with the `alias` of the environment appended to the URL.

API endpoints for both `master` and `dev` environments would follow the format of:

<Tabs>
  <TabsItem label="master">

```bash
https://[region].hygraph.com/v2/[projectId]/master
```

  </TabsItem>
  <TabsItem label="dev">

```bash
https://[region].hygraph.com/v2/[projectId]/dev
```

  </TabsItem>
</Tabs>

## Promoting environments

When you have made the necessary changes to a schema you want to promote to the master environment, you can do this by renaming the newly created environment to be `master`, overwriting the existing `master` environment and renaming it to something else.

Since environments contain their own content, and webhooks, you will want to make sure you clone a new environment right before you apply the changes and promote, this ensures no loss of data. For projects with multiple users managing content at the same time you make changes to the schema inside an environment, you will probably want to use the <Link href="https://github.com/hygraph/management-sdk" target="_blank">Management SDK</Link>. For more information on how to use our UI to promote an environment to master, click [here](/docs/developer-guides/project/manage-project-environments#promote-environments-to-master).

## Delete an environment

You can delete environments using our UI by following [these steps](/docs/developer-guides/project/manage-project-environments#delete-environments).


---
# Errors

Source: https://hygraph.com/docs/api-reference/basics/errors

## Overview

Hygraph uses conventional HTTP responses codes when returning API requests.

Codes in the 2xx range refer to a successful request, whereas responses in the 4xx range indicate there was an error due to the information you provided, such as invalid [query arguments](/docs/api-reference/content-api/queries#combining-arguments), or [auth](/docs/api-reference/basics/authorization) token.

| Code  | Description                                                                                                |
| ----- | ---------------------------------------------------------------------------------------------------------- |
| `200` | OK - Successful response                                                                                   |
| `400` | [Bad request](#400-bad-request) - Typically due to invalid query arguments                                 |
| `401` | [Unauthorized](#401-unauthorized) - Usually no valid Permanent Auth Token was provided                     |
| `402` | [Payment required](#402-payment-required) - Typically due to an expired trial or API/assetTraffic exceeded |
| `403` | [Unauthorized request](#403-unauthorized-request) - The user needs more permissions                        |
| `404` | Not Found - Typically invalid endpoint or environment requested                                            |
| `413` | Payload too large  - Your request size exceeds the allowed limit                                         |
| `429` | [Too many requests](#429-too-many-requests) - You're making too many requests, slow down                   |
| `500` | [Internal Server Error](#500-internal-server-error) - Something went wrong on our side                     |

A typical GraphQL error will look like the below. The format of the error is typical for any `400` query or mutation request.

```graphql
{
  "errors": [
    {
      "message": "input:1: Field \"idd\" is not defined by type PostWhereInput. Did you mean id?\n"
    }
  ],
  "data": null,
  "extensions": {
    "requestId": "ckff8k1tc0nsg0150cssdkzxm"
  }
}
```

It is clear from the error above that the field `idd` is not part of the Input Type.

<Alert theme="info">

Hygraph will also return the `requestId` which can be used when requesting support.

</Alert>

## `400: Bad request`

Hygraph will return a 400 if there is an error with the request. 400 errors are typically thrown when there is a client-side validation error, such as a missing required argument in your GraphQL query, or a malformed Permanent Auth Token.

<Alert title="Pro Tip" theme="info">

If your Permanent Auth Token is not a valid JWT, you will receive a 400 error.

</Alert>

## `401: Unauthorized`

The endpoint you requested requires a valid [Permanent Auth Token](/docs/api-reference/basics/authorization), or a environment may not exist for this project.

<Alert title="Pro Tip" theme="info">

You might find the following documents useful for this:

- [Authorization](/docs/api-reference/basics/authorization)
- [Permanent auth tokens with specific models](/docs/getting-started/access-and-permissions/content-api-permissions#set-up-a-pat-with-model-specific-permissions)

</Alert>

## `402: Payment required`

Exceeding the API operations and/or the asset traffic limit results in the API being blocked until the new billing period starts.

Queries will return the following 402 error:

> You have exceeded the limits of your project's subscription. To continue using your API, please enable billing under your project's settings to allow for overlimit billing.

You may also get this error after a trial period has expired.

## `403: Unauthorized request`

The user needs more permissions for either the Content API or the Management API.

<Alert title="Pro Tip" theme="info">

You might find the following documents useful for this:

- [Roles and permissions](/docs/developer-guides/project/roles-and-permissions)
- [Permissions](/docs/api-reference/basics/permissions)

</Alert>

## `413: Payload too large`

To ensure delivery of optimal experiences to all customers, an API limit is enforced for request sizes on all GraphQL queries for the shared regions. The rate limiting depends on the current load of the shared region and the subscription plan. These limits can be lifted on dedicated clusters and enterprise plans. Please [contact sales](/contact) for further information.

You'll get a `413` when you exceed the [limit for request size](/docs/api-reference/basics/api-limits#request-size), and you will get a response with the following payload:

```json
{
  "errors": [
    {
      "message": "Payload Too Large"
    }
  ],
  "data": null
}
```

To resolve this issue, reduce the size of your GraphQL query or mutation.

## `429: Too many requests`

To ensure delivery of optimal experiences to all customers, a rate limit is enforced on all GraphQL queries for the shared regions. The rate limiting depends on the current load of the shared region and the subscription plan. These limits can be lifted on dedicated clusters and enterprise plans. Please [contact sales](/contact) for further information.

You'll get a `429` error when you exceed the rate limit.

For exceeding the [number of requests per second limit](/docs/api-reference/basics/api-limits#requests-per-second), you will get a response with the following payload:

```json
{
  "errors": [
    {
      "message": "Too Many Requests"
    }
  ],
  "data": null
}
```

To resolve this issue, retry the request after a brief delay.

For exceeding the [concurrent requests limit](/docs/api-reference/basics/api-limits#concurrent-operations), you will get a response with the following payload:

```json
{
  "errors": [
    {
      "message": "Concurrent operations limit exceeded"
    }
  ],
  "data": null
}
```

To resolve this issue, reduce the volume of your concurrent requests.

<Alert title="Pro Tip" theme="info">

Our document on [API rate limits](/docs/api-reference/basics/api-limits) shares information on limits according to subscription plan, as well as ways of handling API rate limits with [Next.js](/docs/api-reference/basics/api-limits#nextjs), [Gatsby](/docs/api-reference/basics/api-limits#gatsby), and [Nuxt](/docs/api-reference/basics/api-limits#nuxt).

</Alert>

## `500: Internal server error`

`500s` errors could happen in multiple scenarios, whenever there's something wrong on our side.

<Alert title="Pro Tip" theme="info">

If you get a `500` error, make sure to take a look at our <Link href="https://status.hygraph.com/" target="_blank">status page</Link>.

</Alert>


---
# Query complexity

Source: https://hygraph.com/docs/api-reference/basics/query-complexity

## Overview

When working with GraphQL (GQL) queries, it's important to manage the complexity of your queries to ensure efficient and effective data retrieval.

In the context of GQL, **query complexity** refers to the computational resources needed to fulfill a query. The complexity of a query increases with the number of fields and the depth of the query.

- **Scalar fields**: Each scalar field in a query contributes one point to the query complexity.
- **Relations / Unions**: Relations multiply their complexity times the level of nesting in the query.

For example, if a query retrieves a list of posts and each post has multiple comments, the complexity of the query increases with each nested comment.

This guide will help you with the following:

- [How to split up your GQL queries to manage complexity](/docs/api-reference/basics/query-complexity#splitting-gql-queries)
- [How to optimize union queries](/docs/api-reference/basics/query-complexity#union-queries)
- [How to use the complexity tree JSON output to calculate the cost of your queries](/docs/api-reference/basics/query-complexity#complexity-tree-json-output)

<Alert theme="info" title="Pro Tip">

Some queries can be heavy on the database - especially due to heavy nesting or filtering - and in those cases, query splitting can help prevent them from failing.

The complexity tree shown [here](/docs/api-reference/basics/query-complexity#complexity-tree-json-output) gives you information about the estimated cost of a query. If the JSON output shows values that are really high compared to the others, it might make sense to split the query.

While query complexity matters, the reason a query fails can also be due to the number of entries, the concurrency of the query in a short period of time, or the general load of the infrastructure. If your query fails and the complexity tree does not show any significantly high values, please contact support so they can help you investigate the reason and find a solution.

</Alert>

## Splitting GQL queries

To manage query complexity, you can split your GQL queries into smaller, more manageable parts:

| Suggestion                                                                                                          | Description                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Limit the depth of your queries](/docs/api-reference/basics/query-complexity#example-1-limiting-query-depth)       | Avoid deeply nested queries. Instead, break them up into multiple smaller queries. This can help reduce the complexity and make your queries more efficient.                            |
| [Fetch only necessary fields](/docs/api-reference/basics/query-complexity#example-2-fetching-only-necessary-fields) | Minimize the number of fields you're retrieving in each query. Only fetch the fields that are necessary for your current operation.                                                     |
| [Use pagination](/docs/api-reference/basics/query-complexity#example-3-using-pagination)                            | Hygraph supports various arguments for paginating content entries. By using these features, you can manage the amount of data retrieved in each query, thereby reducing the complexity. |

Remember that the goal is to **reduce the complexity of your queries to ensure efficient and effective data retrieval**. By limiting the depth of your queries, fetching only necessary fields, and using pagination, you can manage the complexity of your GQL queries effectively.

The following examples show you how you can split your GQL queries:

### Example 1: Limiting query depth

Instead of a deeply nested query like this:

```graphql
{
  posts {
    id
    comments {
      id
      author
      replies {
        id
        text
        user {
          id
          name
        }
      }
    }
  }
}
```

You can split it into two separate queries:

<Tabs panelHeight={230}>
  <TabsItem label="Query 1">

```graphql
{
  posts {
    id
    comments {
      id
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Query 2">

```graphql
{
  comments(id: "...") {
    id
    author
    replies {
      id
      text
      user {
        id
        name
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

### Example 2: Fetching only necessary fields

Intead of retrieving all fields, like this:

```graphql
{
  post(where: { id: "..." }) {
    id
    title
    body
    author
    comments
  }
}
```

You can retrieve only the necessary fields, like this:

```graphql
{
  post(where: { id: "..." }) {
    id
    title
  }
}
```

### Example 3: Using pagination

Hygraph supports various arguments for paginating content entries:

- **`first`**: Seek forwards from the start of the result set.
- **`last`**: Seek backwards from the end of the result set.
- **`skip`**: Skip result set by a given amount.
- **`before`**: Seek backwards before a specific ID.
- **`after`**: Seeks forwards after a specific ID.

<Alert theme="warning">
You cannot combine `first` with `before`, or `last` with `after`.
</Alert>

The default result size of results returned by queries fetching multiple entries is 10. You can provide a maximum of 100 to the **`first`**, or **`last`** arguments.

<Alert theme="info" title="Pro Tip">
- The limit of 10/100 applies to projects created after 14-06-2022.
- Projects created before that date have a limit of 100/1000.
- To learn more about this, check out our document on [Pagination](/docs/api-reference/content-api/pagination).
</Alert>

You can use **`first`**, **`last`**, **`skip`**, **`before`**, and **`after`** arguments with any nested relations. In the following example, the `posts` model has `comments`:

```graphql
{
  posts {
    id
    comments(first: 6, skip: 6) {
      id
      createdAt
    }
  }
}
```

## Union queries

[Union types](/docs/api-reference/schema/field-types#union) allow to setup relational fields that point to different model types, while this feature allows for very flexible modelling of content, it can also open the door to queries that might not perform as well and could use some optimizations. Below we document means to optimize querying for content that is backed by a Union relation.

Unions are typically queried like so:

```graphql
{
  page(where: { id: "ckrks0ge0334m0b52onduq7r2" }) {
    id
    title
    blocks {
      __typename
      ... on Hero {
        title
        ctaLink
      }
      ... on Grid {
        title
        subtitle {
          markdown
        }
      }
      ... on Gallery {
        photos {
          url
          handle
        }
      }
    }
  }
}
```

As schemas evolve and Union relations expand to many models, querying unions this way can become problematic. Particularly when every single possible type is queried with this format within the same query.

## Optimizing union queries

We offer two ways of optimizing your union queries:
- Enhanced Query Splitting with Entity Type **(Preferred solution)**
- Optimizing union queries using Node

### Enhanced query splitting with Entity type

<Alert theme="info" title="Please note">
This is the preferred solution, as it offers significantly better performance.
</Alert>

Hygraph has introduced an improved query splitting feature using the `Entity` type and `entities` query entrypoint.

This approach is particularly beneficial for handling complex union relationships and modular components.

<Alert theme="info">
This new feature reflects Hygraph's commitment to providing advanced solutions for handling complex GraphQL queries with ease and efficiency.
</Alert>

#### Implementation

The `Entity` type provides a more streamlined approach compared to the traditional Node interface. It makes use of the typename to substantially increase performance.

To do this, follow these two steps:

**Step 1: Initial query using Entity type**

This initial query fetches `id` and `__typename` for each block within a page, preparing for the detailed query in the next step.

```graphql
query {
  page {
    id
    blocks {
      __typename
      ... on Entity {
        id
      }
    }
  }
}
```

**Step 2: Detailed query for specific types**

The second query specifically targets `Hero`, `Grid`, and `Gallery` entities based on the `id` and `__typename` obtained from the first query. Results are returned in the order of the `where` input. 

```graphql
query {
  entities(where: [{id: "ckrks0ge0334m0b52ienf67ag", typename: "Hero", stage: "DRAFT"},
                   {id: "ckrks0ge0334m0b52firha74a", typename: "Grid", stage: "DRAFT"},
                   {id: "ckrks0ge0334m0b52ifh2sd6a", typename: "Gallery", stage: "DRAFT"}]) {
    ... on Hero {
      id
      title
    }
    ... on Grid {
      id
      layout
    }
    ... on Gallery {
      id
      images
    }
  }
}
```

<Alert theme="warning">
Please note that `entities` is a top-level type.
</Alert>

#### Benefits

|Benefit                  |Description                                                              |
|-------------------------|-------------------------------------------------------------------------|
|Reduced Query Complexity |Simplifies queries by splitting them into manageable parts.              |
|Enhanced Performance     |Improves efficiency by reducing the load in fetching complex data types. |
|Flexible Data Fetching   |Offers more control and precision in querying specific content types.    |

#### Example Use Case

Consider a website with a dynamic layout consisting of `Hero`, `Grid`, and `Gallery` sections.  **Enhanced query splitting with Entity type** would allow for efficient identification and retrieval of specific content types, ensuring high performance and flexibility in data handling.

### Optimizing union queries using Node

In order to avoid performance impacts due to a large number of Union types in a relation, it is possible to change the way the content is queried so that it is done in a 2 step approach.

Below we will be using the same query from the previous section as an example:

**Step 1: Find out which documents are in fact connected**

        We will get the `__typename` and the `id` for all the connected documents in the union relation by using the Node interface like so:

        <Tabs panelHeight={300}>

    <TabsItem label="Query">

        ```graphql
        {
          page(where: { id: "ckrks0ge0334m0b52onduq7r2" }) {
            id
            title
            blocks {
              __typename
              ... on Node {
                id
              }
            }
          }
        }
        ```

        </TabsItem>

    <TabsItem label="Response">

        ```graphql
        {
        "data": {
            "page": {
                "id": "ckrks0ge0334m0b52onduq7r2",
                "title": "Sample Page 1",
                "blocks": [
                {
                    "id": "cks8t3o943h1l0d099v8xd072",
                    "__typename": "Hero"
                },
                {
                    "id": "cksj3dxww0o2r0c57savzceub",
                    "__typename": "Grid"
                },
                {
                    "id": "cksrocxds3mwa0a07rdtj7qvx",
                    "__typename": "Grid"
                },
                {
                    "id": "cks8t36i83iq70b6035caxp6n",
                    "__typename": "Gallery"
                }
                ]
            }
        }
        }
        ```

        </TabsItem>

    </Tabs>

**Step 2: Query the connected types by `id`**

    With the retrieved information we can construct queries dynamically to fetch the affected documents. Considering the response we received from the previous query in **Step 1**, we will now go over the response and generate another query that will in fact get only the connected documents by `id`:

    ```graphql
    query heroBlocks {
      heros(where: { id_in: ["cks8t3o943h1l0d099v8xd072"] }) {
        title
        ctaLink
      }
    }

    query gridBlocks {
      grids(
        where: {
          id_in: ["cksj3dxww0o2r0c57savzceub", "cksrocxds3mwa0a07rdtj7qvx"]
        }
      ) {
        title
        subtitle {
          markdown
        }
      }
    }

    query galleryBlocks {
      galleries(where: { id_in: ["cks8t36i83iq70b6035caxp6n"] }) {
        photos {
          url
          handle
        }
      }
    }
    ```

    Alternatively, you can combine these into a single query by using aliasing:

    ```graphql
    query blocks {
      heroBlocks: heros(where: { id_in: ["cks8t3o943h1l0d099v8xd072"] }) {
        title
        ctaLink
      }
      gridBlocks: grids(
        where: {
          id_in: ["cksj3dxww0o2r0c57savzceub", "cksrocxds3mwa0a07rdtj7qvx"]
        }
      ) {
        title
        subtitle {
          markdown
        }
      }
      galleryBlocks: galleries(
        where: { id_in: ["cks8t36i83iq70b6035caxp6n"] }
      ) {
        photos {
          url
          handle
        }
      }
    }
    ```

## Complexity tree JSON output

The complexity tree JSON output provides a detailed breakdown of the estimated and actual costs of your GraphQL query. This information can help you understand the computational resources required to fulfill your query and guide you in optimizing your queries for better performance.

<Alert theme="info" title="Pro Tip">
To get the complexity tree JSON for your query, you need to add the `"x-inspect-complexity": true` header to the playground.
</Alert>

### JSON Output

Here is a brief explanation of the keys in the JSON output:

- **`total_estimated_docs`:** The total number of documents estimated to be fetched by the query.
- **`total_actual_docs`:** The total number of documents actually fetched by the query.
- **`total_estimated_cost`:** The total estimated cost of the query. This includes the cost of fetching documents and any additional costs.
- **`total_actual_cost`:** The total actual cost of the query.
- **`complexityTree`:** A nested structure that breaks down the cost of each field in the query.

Each node in the `complexityTree` has the following keys:

- **`field_name`:** The name of the field in the query.
- **`xpath`:** The path to the field in the query.
- **`estimated_no_of_docs`:** The estimated number of documents fetched by this field.
- **`additional_cost`:** Any additional cost associated with this field.
- **`estimated_cost`:** The total estimated cost of this field (the sum of `estimated_no_of_docs` and `additional_cost`).
- **`actual_no_of_docs`:** The actual number of documents fetched by this field.
- **`actual_cost`:** The actual cost of this field.
- **`children`:** Any nested fields within this field. Each child is also a node with the same structure.

<Alert theme="info" title="Pro Tip">
Nested objects multiply the estimated complexity by the pagination size default 10 (max 100).

This is important to keep in mind when dealing with nested queries, as they can significantly increase the complexity of your query.
</Alert>

### JSON Output Example

Consider the following query and its related complexity tree `JSON` output:

<Tabs panelHeight={280}>
  <TabsItem label="Query">

```graphql
query Example {
  posts {
    title
    comments {
      text
      authors {
        name
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="JSON Output">

```json
{
  "complexity": {
    "total_estimated_docs": 1110,
    "total_actual_docs": 0,
    "total_estimated_cost": 1116,
    "total_actual_cost": 0,
    "complexityTree": {
      "field_name": "Root",
      "estimated_no_of_docs": 0,
      "additional_cost": 0,
      "estimated_cost": 0,
      "actual_no_of_docs": 0,
      "actual_cost": 0,
      "children": [
        {
          "field_name": "posts",
          "xpath": "posts.#",
          "estimated_no_of_docs": 10,
          "additional_cost": 2,
          "estimated_cost": 12,
          "actual_no_of_docs": 0,
          "actual_cost": 0,
          "children": [
            {
              "field_name": "title",
              "estimated_no_of_docs": 0,
              "additional_cost": 0,
              "estimated_cost": 0,
              "actual_no_of_docs": 0,
              "actual_cost": 0
            },
            {
              "field_name": "comments",
              "xpath": "posts.#.comments.#",
              "estimated_no_of_docs": 100,
              "additional_cost": 2,
              "estimated_cost": 102,
              "actual_no_of_docs": 0,
              "actual_cost": 0,
              "children": [
                {
                  "field_name": "text",
                  "estimated_no_of_docs

": 0,
                  "additional_cost": 0,
                  "estimated_cost": 0,
                  "actual_no_of_docs": 0,
                  "actual_cost": 0
                },
                {
                  "field_name": "authors",
                  "xpath": "posts.#.comments.#.authors.#",
                  "estimated_no_of_docs": 1000,
                  "additional_cost": 2,
                  "estimated_cost": 1002,
                  "actual_no_of_docs": 0,
                  "actual_cost": 0,
                  "children": [
                    {
                      "field_name": "name",
                      "estimated_no_of_docs": 0,
                      "additional_cost": 0,
                      "estimated_cost": 0,
                      "actual_no_of_docs": 0,
                      "actual_cost": 0
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

```

  </TabsItem>
</Tabs>

This JSON output shows us that the total estimated cost of the query is 1116, which includes fetching 1110 documents and additional costs. However, since the query did not return any content for this example(there was no real content in the project), the actual costs and documents fetched are 0. Despite this, the query is still costly due to the nested structure, hence the high estimated cost.

The `complexityTree` provides a breakdown of the costs for each field in the query. For example, the `posts` field is estimated to fetch 10 documents with an additional cost of 2, resulting in an estimated cost of 12. Within the `posts` field, the `comments` field is estimated to fetch 100 documents with an additional cost of 2, resulting in an estimated cost of 102. The `authors` field within `comments` is estimated to fetch 1000 documents with an additional cost of 2, resulting in an estimated cost of 1002. This is because of the multiplication of nested fields that we mentioned before.

<Alert theme="info" title="Pro Tip">
By examining the `complexityTree`, you can identify which fields contribute the most to the complexity of your query and optimize accordingly.

Keep in mind that nested objects multiply the estimated complexity by the pagination size, so be mindful of this when structuring your queries.
</Alert>


---
# Troubleshooting

Source: https://hygraph.com/docs/api-reference/basics/troubleshooting

## Can't access part of the functionality

This might be a [permissions](/docs/api-reference/basics/permissions) issue.

Take into consideration that while Management API permissions are global, content permissions are environment specific.

If you're getting a [401 error](/docs/api-reference/basics/errors#401-unauthorized), the endpoint you requested requires a valid [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens), or a environment may not exist for this project.

## Queries not returning complete results

This is a [pagination](/docs/api-reference/content-api/pagination) issue.

The default size of results returned by queries fetching multiple entries is 10. You can provide a maximum of 100 to the first, or last arguments.

The limit of 10/100 applies to projects created after 14-06-2022. Projects created before that date have a limit of 100/1000.

Our pagination document also contains information about [pagination limits](/docs/api-reference/content-api/pagination#pagination-limits), [nested pagination](/docs/api-reference/content-api/pagination#nested-pagination), and [relay cursor connections](/docs/api-reference/content-api/pagination#relay-cursor-connections).

## My query is too slow

This could be a [query complexity issue](/docs/api-reference/basics/query-complexity). Our document on [splitting GraphQL queries](/docs/api-reference/basics/query-complexity#splitting-gql-queries) in order to reduce their complexity, suggests three possible solutions:

- [Limiting query depth](/docs/api-reference/basics/query-complexity#example-1-limiting-query-depth)
- [Fetching only necessary fields](/docs/api-reference/basics/query-complexity#example-2-fetching-only-necessary-fields)
- [Using pagination](/docs/api-reference/basics/query-complexity#example-3-using-pagination)

The document also contains information on [union query optimization](/docs/api-reference/basics/query-complexity#union-queries), and on [how to use the complexity tree JSON output to calculate the cost of your queries](/docs/api-reference/basics/query-complexity#complexity-tree-json-output).

## No invite found with this code

If when accepting an invitation to a project you get the error message `No invite found with this code`, ensure you are logged in with the right account.

## Too many requests

This is related to our [API limits](/docs/api-reference/basics/api-limits). When you exceed them, you get a [429 error](/docs/api-reference/basics/errors#429-too-many-requests).

Our API limits document contains information on how to tackle this using [Next.js](/docs/api-reference/basics/api-limits#nextjs), [Gatsby](/docs/api-reference/basics/api-limits#gatsby), and [Nuxt](/docs/api-reference/basics/api-limits#nuxt).

<Alert theme="info">

The API limits depend on the current load of the shared region and the subscription plan. These limits can be lifted on dedicated clusters and enterprise plans. You can [contact sales](/contact) to request a custom plan.

</Alert>

## (Free plans only) Asset traffic limit reached

As soon as a project on a **free plan** exceeds its asset traffic limit, all asset URLs return the following error:
“You have exceeded the asset traffic limits of your project's subscription. To continue serving assets, please enable billing under your project’s settings to allow for overlimit billing.”

You can either:

- Wait until the limit resets to 0 at the start of the next billing cycle. Once the new cycle begins, you can start querying your assets.
- Upgrade to a paid plan, which immediately resets the limit to 0. In this case, reach out to Hygraph Support so we can verify that the project has been unblocked.


---
# Usage metrics API reference

Source: https://hygraph.com/docs/api-reference/basics/usage-metrics

The Hygraph Management API gives you programmatic access to your project's usage and safeguard metrics. You can use this data to build external dashboards or set up alerting for your own monitoring stack. This data is also available in the [Usage dashboard](/docs/developer-guides/project/usage-dashboard).

## Prerequisites

To query usage metrics, your Permanent Auth Token must include the **Read observability data** Management API permission. For more information, see [Management API permissions](/docs/getting-started/access-and-permissions/management-api-permissions#pats-experimental-ai-usage).

## Query structure

On the Management API, the `usage` field exists on:

- `viewer.project`: Project-level metrics.
- `viewer.project.environment`: Environment-level metrics.

```graphql
viewer {
  project(id: $projectId) {
    usage(end: $end, start: $start) {
      # project-level metrics
    }
    environment(id: $environmentId) {
      usage(end: $end, start: $start) {
        # environment-level metrics
      }
    }
  }
}
```

Replace `$projectId` and `$environmentId` with the IDs from your project settings. You can find the Project ID and environment ID in the project URL: `https://app.hygraph.com/<projectId>/<environmentId>/`.

### Arguments

| Argument | Type | Description |
|---|---|---|
| `end` | `DateTime!` | End of the requested date range. |
| `start` | `DateTime!` | Start of the requested date range. The API only returns data within your plan’s **retention window**. |

Retention depends on your plan: 

- Hobby plans: 30 days
- Paid plans: 365 days

Requesting a `start` date earlier than your retention window does not return an error. The API clips the start to the earliest retained date and returns data from that point forward.

## Metrics

### Billing metrics

Billing metrics are summed across all environments at project level. These metrics reflect consumption against your plan limits.

| Field | Units | Description |
|---|---|---|
| `apiOperations` | Request count per day | External Content API requests, excluding Studio traffic. Aggregated for usage reporting. |
| `assetTraffic` | Bytes per day | Asset data transferred, counted toward asset bandwidth usage. |

### Technical safeguard metrics

Technical safeguard metrics relate to the same limits as [API limits](/docs/api-reference/basics/api-limits). They exist on both project and environment usage. For interpreting these limits, **environment** usage is usually the best match, because limits apply **per environment**.

**At project level** (`viewer.project { usage }`):

- `maxRps*`, `maxConcurrency*`, `maxRequestSize*`: For each day in the range, the maximum value observed across all environments. This is the largest per-environment value for that day, not a single merged peak across the whole project.
- `*OverLimit*`: For each day in the range, the total count across all environments.

**At environment level** (`viewer.project.environment { usage }`):

- `maxRps*`, `maxConcurrency*`, `maxRequestSize*`: For each day in the range, the maximum value observed for that environment only.
- `*OverLimit*`: For each day in the range, the total count for that environment only.

| Field | Description |
|---|---|
| `maxRpsQueries` | Peak requests per second for queries. |
| `maxRpsMutations` | Peak requests per second for mutations. |
| `maxConcurrencyQueries` | Peak in-flight concurrent operations for queries. |
| `maxConcurrencyMutations` | Peak in-flight concurrent operations for mutations. |
| `maxRequestSizeQueries` | Largest GraphQL payload size observed for queries. |
| `maxRequestSizeMutations` | Largest GraphQL payload size observed for mutations. |
| `rpsOverLimitQueries` | Requests that exceeded the RPS limit for queries. |
| `rpsOverLimitMutations` | Requests that exceeded the RPS limit for mutations. |
| `concurrencyOverLimitQueries` | Requests that exceeded the concurrency limit for queries. |
| `concurrencyOverLimitMutations` | Requests that exceeded the concurrency limit for mutations. |
| `requestSizeOverLimitQueries` | Requests that exceeded the request size limit for queries. |
| `requestSizeOverLimitMutations` | Requests that exceeded the request size limit for mutations. |

## Response

| Field | Type | Description |
|---|---|---|
| `timestamps` | `[DateTime!]!` | Start of each day in the date range. |
| `values` | `[Float!]!` | One value per day in the date range, in the same order. |

Metrics update once per day and responses are cached for a short interval. Avoid polling more frequently than every few minutes. Data for the current day may be incomplete; use the previous day's data for reliable trend analysis.

## Example query

This query returns project-level billing metrics and environment-level safeguard metrics over a custom date range.

<Tabs>
  <TabsItem label="Query">
```graphql
query UsageAndSafeguards {
  viewer {
    project(id: "Your_project_ID") {
      usage(end: "2026-05-08T00:00:00.000Z", start: "2026-05-06T00:00:00.000Z") {
        apiOperations {
          timestamps
          values
        }
        assetTraffic {
          timestamps
          values
        }
      }
      environment(id: "Your_environment_ID") {
        usage(end: "2026-05-08T00:00:00.000Z", start: "2026-05-06T00:00:00.000Z") {
          maxRpsQueries {
            timestamps
            values
          }
          rpsOverLimitQueries {
            timestamps
            values
          }
          maxConcurrencyMutations {
            timestamps
            values
          }
          concurrencyOverLimitMutations {
            timestamps
            values
          }
          maxRequestSizeMutations {
            timestamps
            values
          }
          requestSizeOverLimitMutations {
            timestamps
            values
          }
        }
      }
    }
  }
}
```
  </TabsItem>
  <TabsItem label="Response">
```json
{
  "data": {
    "viewer": {
      "project": {
        "usage": {
          "apiOperations": {
            "timestamps": [
              "2026-05-06T00:00:00.000Z",
              "2026-05-07T00:00:00.000Z",
              "2026-05-08T00:00:00.000Z"
            ],
            "values": [164556, 156144, 202296]
          },
          "assetTraffic": {
            "timestamps": [
              "2026-05-06T00:00:00.000Z",
              "2026-05-07T00:00:00.000Z",
              "2026-05-08T00:00:00.000Z"
            ],
            "values": [4819734309, 9047785649, 6026574533]
          }
        },
        "environment": {
          "usage": {
            "maxRpsQueries": {
              "timestamps": [
                "2026-05-06T00:00:00.000Z",
                "2026-05-07T00:00:00.000Z",
                "2026-05-08T00:00:00.000Z"
              ],
              "values": [47, 31, 50]
            },
            "rpsOverLimitQueries": {
              "timestamps": [
                "2026-05-06T00:00:00.000Z",
                "2026-05-07T00:00:00.000Z",
                "2026-05-08T00:00:00.000Z"
              ],
              "values": [0, 0, 99]
            },
            "maxConcurrencyMutations": {
              "timestamps": [
                "2026-05-06T00:00:00.000Z",
                "2026-05-07T00:00:00.000Z",
                "2026-05-08T00:00:00.000Z"
              ],
              "values": [1, 1, 1]
            },
            "concurrencyOverLimitMutations": {
              "timestamps": [
                "2026-05-06T00:00:00.000Z",
                "2026-05-07T00:00:00.000Z",
                "2026-05-08T00:00:00.000Z"
              ],
              "values": [0, 0, 0]
            },
            "maxRequestSizeMutations": {
              "timestamps": [
                "2026-05-06T00:00:00.000Z",
                "2026-05-07T00:00:00.000Z",
                "2026-05-08T00:00:00.000Z"
              ],
              "values": [36309, 12539, 0]
            },
            "requestSizeOverLimitMutations": {
              "timestamps": [
                "2026-05-06T00:00:00.000Z",
                "2026-05-07T00:00:00.000Z",
                "2026-05-08T00:00:00.000Z"
              ],
              "values": [0, 0, 0]
            }
          }
        }
      }
    }
  }
}
```
  </TabsItem>
</Tabs>

---
# Webhooks

Source: https://hygraph.com/docs/api-reference/basics/webhooks

Hygraph webhooks are a fundamental method for observing changes that happen to content within your project.

Whether new content is published, or existing is updated, subscribe to these events, and get notified via a `POST`, `DELETE`, `PUT`, or `GET` request to perform your own custom business logic.

For example, you could use webhooks for:

- Syncing data to external search engine,
- Syncing data with external PIM,
- Redeploying your static website when content or assets change,
- Triggering email campaigns based on new content added.
- Push messages into Slack.

<Alert theme="warning">
**Webhooks are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.
</Alert>

## Triggers

Triggers can be configured to listen to one or more content model, stage, and action events.
It is also possible to specify a trigger source, which allows triggering only when content is changed by the specified source: a [Permanent Auth Token (PAT)](/docs/api-reference/basics/authorization#permanent-auth-tokens), a project member editing content via the webapp or via public API.

| Trigger       |                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| Content Model | All models, including `Asset`                                                                                      |
| Stage         | Draft, Published, and [custom content stages](/docs/api-reference/content-api/content-stages)                      |
| Action        | Create, Update, Delete, Publish, Unpublish, and Transition Step                                                                     |
| Source        | [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens), Project Member, Public API |

<Alert theme="warning">
Ensure that your system is set up to respond to webhook requests as quickly as possible. As soon as Hygraph receives an HTTP 2xx status code, we  process the next webhook request. This prevents any delays or failure in webhook delivery.

Note the following timeouts:

- Webhook requests time out after 3000 ms (3 seconds).
- The current retry policy is 4 retries on top of the initial request, that is, 5 requests in total.

We recommend that you should not set up slow operations, such as builds within the webhook.
</Alert>

## Receiving a webhook

<Alert theme="info">
Once events occur, a new webhook will be queued. It could be several minutes before a webhook is triggered, so make sure to create your application with this in mind.
</Alert>

Once an event occurs, data is sent as JSON in a `POST`, `DELETE`, `PUT`, or `GET` request body to the configured URL. The contents of the request always contain the `operation`, and `data` of the event.

The `data` object will always contain the `__typename`, `id` and `stage` keys.

If the webhook is configured to include entry payloads, the following keys will also be included inside the `data` object:

- All other non-localized fields on the entry.
- The `id` and `__typename` of any related entries.
- An optional `localizations` array, containing any localized fields on the entry.

The snapshot of the current stage is only sent in the webhook body. This means that:

- Create, Update, and Delete actions only send the draft version.
- Publishing and Unpublishing actions only send the published version.

## Securing webhooks

It is best to protect the endpoints which your webhooks invoke. This prevents unauthorized actions on your server, and better protects your users from any suspicious activity.

You should set a shared `secret key` on your webhook, which can be used to validate the request came from Hygraph.

![Hygraph webhook secret key](/images/docs/api-reference/basics/webhook-secret-key.png)

Hygraph will send the header `gcms-signature` on webhooks with a shared secret key set.

A `gcms-signature` header value looks like this:

```
sign=x0jU8z7AXAARIDBgsiVyfOG000wb2HhqN/mxl6+RSMk=, env=test, t=1631270481036
```

## Webhooks & assets

When using webhooks with the Hygraph Asset Management System, remember that asset entry creation and asset uploads are asynchronous processes.

The asset entry is created before the upload finishes, so "create" webhooks are triggered before the upload completes. This can cause external systems to fail if they expect the asset to be available when they receive the "create" webhook.

When the asset entry is created, its status is `ASSET_CREATE_PENDING`. It only becomes accessible via its URL once the status changes to `ASSET_UPLOAD_COMPLETE`.

The webhook system sends an `UPDATE` action for the asset model when the upload status updates to `ASSET_UPLOAD_COMPLETE`.

For example:

<Tabs panelHeight={400}>
  <TabsItem label="Create webhook">
    ```graphql
    {
      "operation": "create",
      "data": {
        "__typename": "Asset",
        <-- typical webhook payload -->
        "localizations": [
          {
            <-- asset fields -->
            "upload": {
              "error": null,
              "expiresAt": "2025-03-19T17:14:34+00:00",
              "status": "ASSET_CREATE_PENDING"
            },
          }
        ],
      }
    }
    ```
  </TabsItem>
  <TabsItem label="Update webhook">
    ```graphql
    {
      "operation": "update",
      "data": {
        "__typename": "Asset",
        "id": "cm8g1gg9n003c07upws5mpn9r",
        "localizations": [
          {
            "fileName": "gold_logo.png",
            "handle": "cm8g1gg9n003d07upsgkl6rwh",
            "height": 1000,
            "locale": "en",
            "mimeType": "image/png",
            "size": 196374,
            "upload": {
              "status": "ASSET_UPLOAD_COMPLETE"
            },
            "width": 1000
          }
        ],
        "stage": "DRAFT"
      }
    }
    ```
  </TabsItem>
</Tabs>

<Alert theme="info" title="Pro Tip">

Check the `data.localizations[0].upload.status` information. It will be being pending on create, and when it's complete it will show an update webhook.

</Alert>

### Webhooks status for assets

| STATUS                  | DESCRIPTION                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `ASSET_CREATE_PENDING`  | A new asset entry has been created but the asset has not yet been uploaded.                         |
| `ASSET_UPLOAD_COMPLETE` | The asset upload is complete.                                                                       |
| `ASSET_UPDATE_PENDING`  | An existing asset entry has started the update process but the new asset has not yet been uploaded. |
| `ASSET_ERROR_UPLOAD`    | An error has occurred during asset creation & upload process.                                       |

## Validating webhook signatures

Using the `gcms-signature` header, you can validate the request came from Hygraph.

You'll need to generate a HMAC with the SHA256 hash function to generate a signature you can use to compare against the `gcms-signature` header.

### Hygraph utils

To make things easier for developers working with Node, we've released a small utility that will construct a new signature for you, with your values.

<Alert theme="info">
Be sure to use the original, unmodified request body when verifying webhook signatures. Avoid parsing the request first, for example with `req.json()`, as this can change the payload and cause signature verification to fail.
</Alert>

```bash
npm install @hygraph/utils
```

<Tabs>
  <TabsItem label="Node">

```js
const { verifyWebhookSignature } = require('@hygraph/utils');

const secret = 'rCNwyiloY3oJYYkxgpBXaleIiUv5MYlx';

const body = '...'; // Raw request text, that is req.text()
const signature = '...'; // Typically req.headers['gcms-signature']

const isValid = verifyWebhookSignature({ body, signature, secret });
```

  </TabsItem>
</Tabs>

You'll need the request body and headers to pass to `verifyWebhookSignature`.

If `isValid` is truthy, then you can safely execute your webhook handler code knowing the request is genuine, otherwise you should abort any further action.

### Manual verification

You may also verify webhook signatures manually by generating your own signature using whatever cryptographic library can generate a SHA256 digest.

Let's break the `gcms-signature` header down:

```
sign=x0jU8z7AXAARIDBgsiVyfOG000wb2HhqN/mxl6+RSMk=, env=master, t=1631270481036
```

- `sign=` is the signature
- `env=` is the environment of the Hygraph project
- `t=` is the timestamp of the event

#### Step 1: Extract the signature and timestamp from the header

First you'll need to get the signature, and timestamp from the header so they can be used to construct a new payload. If you're using JavaScript, it could look something like this:

```jsx
const [rawSign, rawEnv, rawTimestamp] = signature.split(', ');

const sign = rawSign.replace('sign=', '');
const EnvironmentName = rawEnv.replace('env=', '');
const Timestamp = parseInt(rawTimestamp.replace('t=', ''));
```

#### Step 2: Prepare the payload string

Use req.text() to read the raw request body. Webhook signatures must be verified against the exact payload sent by Hygraph. Re-serializing a parsed object can change the payload and cause verification to fail.

You'll next need to create a string of the payload that will be hashed, using the request body. If you're using JavaScript, it could look something like:

```
let payload = JSON.stringify({
  Body: req.text(),
  EnvironmentName,
  TimeStamp: Timestamp,
});
```

#### Step 3: Generate the signature

Next, you'll want to generate the digest for comparison. If you're using JavaScript, it could look something like:

```jsx
const { createHmac } = require('crypto');

const hash = createHmac('sha256', secret).update(payload).digest('base64');
```

#### Step 4: Compare the signatures match!

All that's left to do is compare that the `sign=` value and `hash` match. If you're using JavaScript, this may look something like:

```jsx
const isValid = sign === hash;
```

## Localizations with webhooks

If the webhook is configured to include entry payloads, all localized fields on the entry will be included in the webhook body under the `localizations` key. See the section below for [some examples](#example-payload).

Webhook events are scoped to the entry and are **not** locale specific. For example, if publishing changes to an `en` entry localization, the webhook will still include any other localized versions of that entry in the payload.

## Example payload

Below are examples of an event on `DRAFT`, `PUBLISHED` and a custom QA stage, which include the entry payload. There is also an example without the entry payload included.
Additionally, we also have an example of an event for a workflow transition step, with and without the entry payload.

In the examples below we have a `Post` model.

<Tabs panelHeight={550}>
  <TabsItem label="Draft">

```json
{
  "operation": "create",
  "data": {
    "__typename": "Post",
    "content": "Start using webhooks today, for free.",
    "createdAt": "2020-09-16T13:11:57.345138+00:00",
    "description": "This is a description",
    "id": "ckf5emloo021s0161iqos7enp",
    "image": {
      "__typename": "Asset",
      "id": "ckf5em5hc02100157x5n00lwb"
    },
    "localizations": [
      {
        "locale": "en",
        "title": "Hygraph Webhook Payload Changes"
      }
    ],
    "publishedAt": null,
    "stage": "DRAFT",
    "updatedAt": "2020-09-16T13:11:57.345138+00:00"
  }
}
```

  </TabsItem>
  <TabsItem label="Published">

```json
{
  "operation": "publish",
  "data": {
    "__typename": "Post",
    "content": "Start using webhooks today, for free.",
    "createdAt": "2020-09-16T13:11:57.345138+00:00",
    "description": "This is a description",
    "id": "ckf5emloo021s0161iqos7enp",
    "image": {
      "__typename": "Asset",
      "id": "ckf5em5hc02100157x5n00lwb"
    },
    "localizations": [
      {
        "locale": "en",
        "title": "Hygraph Webhook Payload Changes!"
      }
    ],
    "publishedAt": "2020-09-16T13:14:12.782833+00:00",
    "stage": "PUBLISHED",
    "updatedAt": "2020-09-16T13:13:50.424325+00:00"
  }
}
```

  </TabsItem>
  <TabsItem label="Custom Stage (QA)">

```json
{
  "operation": "publish",
  "data": {
    "__typename": "Post",
    "content": "Start using webhooks today, for free.",
    "createdAt": "2020-09-16T13:11:57.345138+00:00",
    "description": "This is a description",
    "id": "ckf5emloo021s0161iqos7enp",
    "image": {
      "__typename": "Asset",
      "id": "ckf5em5hc02100157x5n00lwb"
    },
    "localizations": [
      {
        "locale": "en",
        "title": "Hygraph Webhook Payload Changes!"
      }
    ],
    "publishedAt": "2020-09-16T13:14:12.782833+00:00",
    "stage": "QA",
    "updatedAt": "2020-09-16T13:13:50.424325+00:00"
  }
}
```

  </TabsItem>

  <TabsItem label="No payload">

```json
{
  "operation": "publish",
  "data": {
    "__typename": "Post",
    "id": "ckf5emloo021s0161iqos7enp",
    "stage": "PUBLISHED"
  }
}
```

  </TabsItem>

  <TabsItem label="Workflows - With payload">

```json
{
  "operation": "transition_step",
  "data": {
    "__typename": "DemoModel",
    "content": {
      "__typename": "DemoModelContentRichText",
      "json": {
        "children": [
          {
            "children": [
              {
                "text": "This is the first entry."
              }
            ],
            "type": "paragraph"
          }
        ]
      },
      "references": []
    },
    "createdAt": "2025-06-25T09:36:19.662343+00:00",
    "createdBy": {
      "__typename": "User",
      "id": "cmab5qcb900l907uq74xz3lqa"
    },
    "id": "cmcbrf372oqcb08uvr42y0api",
    "image": [
      {
        "__typename": "Asset",
        "id": "cmcaodlnt9xl007vxn6u1g12u"
      }
    ],
    "multimediaContent": null,
    "publishedAt": null,
    "publishedBy": null,
    "scheduledIn": [],
    "slug": "entry-12",
    "stage": "DRAFT",
    "subtitle": null,
    "title": "Entry 12",
    "updatedAt": "2025-06-26T11:52:32.853446+00:00",
    "updatedBy": {
      "__typename": "User",
      "id": "cmab5qcb900l907uq74xz3lqa"
    },
    "workflowStep": "reworkChanges"
  }
}
```

  </TabsItem>

  <TabsItem label="Workflow - No payload">

```json
{
  "operation":"transition_step",
  "data":{
    "__typename":"DemoModel",
    "id":"cmcbrf372oqcb08uvr42y0api",
    "stage":"DRAFT"
  }
}
```

  </TabsItem>
</Tabs>

## Create a webhook

1. In your project, navigate to **Project Settings > Automation > Webhooks**.
2. Click `Add webhook`.
3. Fill out the configuration for your webhook.
4. Click `Add webhook` to save.

### Configuration

- A name for organizing and finding your webhooks
- A short description to inform others what your webhook does
- Toggle if you want to include the payload or not
- The URL to be called
- The content model(s) that will be watched
- The content stage to be watched
- The action to be watched
- Any additional headers to pass along

## Enable / Disable webhooks

1. In your project, navigate to **Project Settings > Automation > Webhooks**.
2. Click the context menu next to the webhook you want to edit.
3. Click **Pause** to disable the webhook.
    - To enable the webhook, click the context menu and then click **Resume**.

## Delete a webhook

1. In your project, navigate to **Project Settings > Automation > Webhooks**.
2. Click the context menu next to the webhook you want to delete, and then click **Delete**.
3. Confirm you want to delete the webhook.

## Webhook logs

Hygraph stores logs for all your webhooks, which can help you debugging webhook calls and checking the returned status codes and responses from your endpoints.

Follow these steps to view your webhook logs:
1. In your project, navigate to **Project Settings > Automation > Webhooks**.
2. Click **View logs** next to the webhook for which you want to check logs.

![Hygraph webhook logs button](/images/docs/api-reference/basics/webhook-logs-button.png)

You will see a list of webhooks being sent to your specified endpoint. The logs include a timestamp, HTTP status code, the content model, the performed action and the duration of the request.

![Hygraph webhook logs overview](/images/docs/api-reference/basics/webhook-log-overview.png)

Clicking on one of the items opens up a detail view, showing you both the request and response payload and the information from the overview. The request and response body is currently truncated at 500kb and 200kb respectively.

![Hygraph webhook logs details](/images/docs/api-reference/basics/webhooks-log-details.png)

<Alert theme="info">
Webhook Logs are currently stored with a retention of 7 days.
</Alert>


---
# Content stages in Hygraph

Source: https://hygraph.com/docs/api-reference/content-api/content-stages

## Overview

You can create your own content stages inside the Hygraph UI, and query content from these stages, as well as publish to.

By default all content is served from the `DRAFT` stage, unless configured otherwise via a Permanent Auth Token, or by filtering.

You can [create custom content stages](/docs/developer-guides/content/content-stages#custom-content-stages) to publish to from `DRAFT`. Each project comes with stages `DRAFT`, and `PUBLISHED`.

<Alert theme="warning">
Custom content stages are available to paid plans. <Link href="https://hygraph.com/pricing" target="_blank">Upgrade your plan</Link>.

**Content stages are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.
</Alert>

## Create a content stage

1. Navigate to your project settings.
2. Open the Content Stages tab.
3. Press "Add Stage" at the bottom of the list of stages.
4. Provide the Display name, API ID, a Color for the label and Description in the modal.
5. Click `Create`.

<Alert theme="info">
Creating content stages besides the two offered by default - `DRAFT` & `PUBLISHED` - is available to paid plans. <Link href="https://hygraph.com/pricing" target="_blank">Upgrade your plan</Link>.
</Alert>

## Edit a content stage

1. Navigate to the content stage you want to edit.
2. Press "edit" in the lower left corner of the stage card.
3. Click `Update` in the lower right corner of the card.

<Alert theme="info">
System content stages - `DRAFT` & `PUBLISHED` - cannot be edited.
</Alert>

## Delete a content stage

1. Navigate to the content stage card you want to delete.
2. Click `Delete` and confirm your choice.

<Alert theme="info">
System content stages - `DRAFT` & `PUBLISHED` - cannot be deleted.
</Alert>

## Publishing content

Hygraph automatically generates a publish mutation for each of your content models, including the asset model.

If the models have localized fields, you can greater control the `locales` you want to publish, and if you want to publish the base entry.

Each time you publish to a content stage, you will create a snapshot of the data as a [version](#versioning).

For example, if we have a product model, the mutation `publishProduct` will exist. You can use this mutation to publish content to a content stage.

| Argument            | Input Tpye                | Description                                                                                         |
| ------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| `where`             | `ProductWhereUniqueInput` | The content entry you want to publish, using a [filter](/docs/api-reference/content-api/filtering). |
| `to`                | `[Stage!]! = [PUBLISHED]` | The target published content stage.                                                                 |
| `locales`           | `[Locale!]`               | Optional locales to publish.                                                                        |
| `publishBase`       | `Boolean = true`          | Whether to publish the base content entry.                                                          |
| `withDefaultLocale` | `Boolean = true`          |                                                                                                     |

<Tabs panelHeight={180}>
  <TabsItem label="Without locales">

```graphql
mutation {
  publishProduct(where: { id: "..." }, to: PUBLISHED) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="With locales">

```graphql
mutation {
  publishProduct(
    where: { id: "..." }
    to: PUBLISHED
    publishBase: true
    locales: [en]
    withDefaultLocale: true
  ) {
    id
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="info" title="Pro Tip">
Every mutation besides `publish` and `unpublish`, will only update the `DRAFT` version.

For instance, when you update an entry in the UI, you are doing an `updateMutation`, which changes the `DRAFT` version.

To update the published version, you would need to publish that `DRAFT`.
</Alert>

## Unpublishing content

Similar to publishing content, you can unpublish from a selected content stage.

For example, if we have a product model, the mutation `unpublishProduct` will exist. You can use this mutation to unpublish content from a content stage.

| Argument        | Input Tpye                | Description                                                                                           |
| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `where`         | `ProductWhereUniqueInput` | The content entry you want to unpublish, using a [filter](/docs/api-reference/content-api/filtering). |
| `from`          | `[Stage!]! = [PUBLISHED]` | The target [content stage](/docs/api-reference/content-api/content-stages) to unpublish from.         |
| `locales`       | `[Locale!]`               | Optional locales to unpublish.                                                                        |
| `unpublishBase` | `Boolean = true`          | Whether to unpublish the base content entry or not.                                                   |

<Tabs panelHeight={180}>
  <TabsItem label="Without locales">

```graphql
mutation {
  unpublishProduct(where: { id: "..." }, from: PUBLISHED) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="With locales">

```graphql
mutation {
  unpublishProduct(
    where: { id: "..." }
    from: PUBLISHED
    unpublishBase: true
    locales: [en]
  ) {
    id
  }
}
```

  </TabsItem>
</Tabs>

## Versioning

Versioning allows you to work non-destructively with content. Make changes, and recover previous versions with Hygraph.

Each time you publish to a content stage, history is written.

<Alert theme="warning">
Versions of documents are kept for a minimum of 30 days, for paid plans. <Link href="https://hygraph.com/pricing" target="_blank">Upgrade your plan</Link> for longer history retention.
</Alert>

### Fetching version history

You can fetch all of the history by `stage`. `history` is a [system field](/docs/api-reference/schema/system-fields#version-history-fields).

For example, let's get all of the `history` for `products`.

<Tabs panelHeight={270}>
  <TabsItem label="Request">

```graphql
{
  products(stage: PUBLISHED) {
    history {
      id
      stage
      revision
      createdAt
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "history": [
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 4,
            "createdAt": "2020-11-02T10:28:24.273413+00:00"
          },
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 3,
            "createdAt": "2020-11-02T10:01:40.453523+00:00"
          },
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 2,
            "createdAt": "2020-11-02T10:01:36.351916+00:00"
          },
          {
            "id": "ckdt47uio02al01044grc4ehf",
            "stage": "PUBLISHED",
            "revision": 1,
            "createdAt": "2020-11-02T10:00:22.14774+00:00"
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="info">
Replace `stage: PUBLISHED` with `stage: QA` to get history from custom stage `QA`.
</Alert>

### Fetching a single version

You can use a the generated `[model]Version` query to fetch a single version of a content entry.

Since models can be complex, and change over time. The `data` field is a JSON field that returns a snapshot of the content entry at that time.

Using the `id`, and `revision` from the previous query, we can fetch the `data` of the version, including the relations metadata.

<Tabs panelHeight={270}>
  <TabsItem label="Request">

```graphql
{
  productVersion(
    where: { id: "ckdt47uio02al01044grc4ehf", revision: 4, stage: PUBLISHED }
  ) {
    id
    stage
    revision
    data
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "productVersion": {
      "id": "ckdt47uio02al01044grc4ehf",
      "stage": "PUBLISHED",
      "revision": 4,
      "data": {
        "id": "ckdt47uio02al01044grc4ehf",
        "name": "Snapback",
        "slug": "snapback",
        "image": {
          "id": "ckdt47ocg02af0104ek5dinsj",
          "__typename": "Asset"
        },
        "stage": "PUBLISHED",
        "prices": [
          {
            "id": "cke1f4fow022h0151b46dd64d",
            "__typename": "Price"
          },
          {
            "id": "cke1f4pq0022f0146btokysn8",
            "__typename": "Price"
          }
        ],
        "category": {
          "id": "cke1erm9s01ov0151p2h1k6bw",
          "__typename": "Category"
        },
        "createdAt": "2020-08-13T18:07:36.201803+00:00",
        "updatedAt": "2020-08-19T13:35:19.916504+00:00",
        "description": {
          "raw": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": ""
                  }
                ]
              }
            ]
          },
          "__typename": "RichText"
        },
        "publishedAt": "2020-11-02T10:28:24.273413+00:00"
      }
    }
  }
}
```

  </TabsItem>
</Tabs>


---
# Filtering

Source: https://hygraph.com/docs/api-reference/content-api/filtering

## Overview

Hygraph automatically creates filters for types you add to your content models. These filters can be applied to a single, or multiple entries, and nested object fields.

The best place to explore all available filters is by using the [API Playground](/docs/api-reference/basics/api-playground).

## Using filters

To filter content entries, simply pass the `where` argument to the query, followed by any of the [filter types](#filter-types) for the fields on your model.

<Alert theme="info" title="Pro Tip">
- All models come with their own custom GraphQL input type. Depending on the field type you want to filter by, there will be different fields you can filter by. String fields will behavior differently to Boolean fields for example.
- **Array fields** only have `contains_all`, `contains_none`, `contains_some` filters available.
- Check out the API Playground to see what types the `where` filter accepts for the fields in your schema.
</Alert>

For example, a `Post` model will have the `where` input types `PostWhereInput` and `PostWhereUniqueInput` on the `posts`, and `postsConnection` query types. These types contain filters specific to that content type.

<Alert theme="warning">
Hygraph does not currently support filtering for Rich Text - even if inside components -, JSON, multi-value fields, colors, or coordinates.
</Alert>

## Filter types

### ID

Entries can be filtered by `id`.

| Matches              | Type    | Behavior                |
| -------------------- | ------- | ------------------------ |
| `id`                 | `ID`    | Equal to                 |
| `id_not`             | `ID`    | Not this (null accepted) |
| `id_in`              | `[ID!]` | One of                   |
| `id_not_in`          | `[ID!]` | Not one of               |
| `id_starts_with`     | `ID`    | Starts with              |
| `id_not_starts_with` | `ID`    | Does not start with      |
| `id_ends_with`       | `ID`    | Ends with                |
| `id_not_ends_with`   | `ID`    | Does not end with        |
| `id_contains`        | `ID`    | Contains                 |
| `id_not_contains`    | `ID`    | Does not contain         |

### String

All String fields can be filtered using:

| Matches                       | Type       | Behavior                 |
| ----------------------------- | ---------- | ------------------------- |
| `[fieldName]_not`             | `String`   | Not this (null accepted)  |
| `[fieldName]_in`              | `[String]` | One of                    |
| `[fieldName]_not_in`          | `[String]` | Not one of                |
| `[fieldName]_starts_with`     | `String`   | Starts with string        |
| `[fieldName]_not_starts_with` | `String`   | Doesn't start with string |
| `[fieldName]_ends_with`       | `String`   | Ends with string          |
| `[fieldName]_not_ends_with`   | `String`   | Doesn't end with string   |
| `[fieldName]_contains`        | `String`   | Includes string           |
| `[fieldName]_not_contains`    | `String`   | Does not include string   |

### Integer

All Integer fields can be filtered using:

| Matches              | Type    | Behavior                |
| -------------------- | ------- | ------------------------ |
| `[fieldName]_not`    | `Int`   | Not this (null accepted) |
| `[fieldName]_in`     | `[Int]` | One of                   |
| `[fieldName]_not_in` | `[Int]` | Not one of               |
| `[fieldName]_lt`     | `Int`   | Less than                |
| `[fieldName]_gt`     | `Int`   | Greater than             |
| `[fieldName]_lte`    | `Int`   | Less than or equal to    |
| `[fieldName]_gte`    | `Int`   | Greater than or equal to |

```graphql
{
  products(where: { quantity: 100 }) {
    quantity
  }

  multipleQuantities: products(where: { quantity_in: [10, 100, 1000] }) {
    quantity
  }
}
```

### Float

All Float fields can be filtered using:

| Matches              | Type      | Behavior                |
| -------------------- | --------- | ------------------------ |
| `[fieldName]_not`    | `Float`   | Not this (null accepted) |
| `[fieldName]_in`     | `[Float]` | One of                   |
| `[fieldName]_not_in` | `[Float]` | Not one of               |
| `[fieldName]_lt`     | `Float`   | Less than                |
| `[fieldName]_gt`     | `Float`   | Greater than             |
| `[fieldName]_lte`    | `Float`   | Less than or equal to    |
| `[fieldName]_gte`    | `Float`   | Greater than or equal to |

```graphql
{
  products(where: { rating: 4.5 }) {
    name
    rating
  }
}
```

### Boolean

All Booleans belonging to your content model can be filtered using the field name directly, as well as appended with `_not`, with a Boolean input type.

| Matches       | Type      | Behavior                                   |
| ------------- | --------- | ------------------------------------------- |
| `[field]`     | `Boolean` | Is                                          |
| `[field]_not` | `Boolean` | Flips boolean (null not taken into account) |

For example, let's filter posts where the custom field `verified` is `true`:

```graphql
{
  posts(where: { verified: true }) {
    id
  }

  posts(where: { verified_not: true }) {
    id
  }
}
```

### Date

All Date fields can be filtered using:

| Matches              | Type     | Behavior                |
| -------------------- | -------- | ------------------------ |
| `[fieldName]_not`    | `Date`   | Not this (null accepted) |
| `[fieldName]_in`     | `[Date]` | One of                   |
| `[fieldName]_not_in` | `[Date]` | Not one of               |
| `[fieldName]_lt`     | `Date`   | Less than                |
| `[fieldName]_gt`     | `Date`   | Greater than             |
| `[fieldName]_lte`    | `Date`   | Less than or equal to    |
| `[fieldName]_gte`    | `Date`   | Greater than or equal to |

```graphql
{
  today: events(where: { day: "2020-10-07" }) {
    day
  }

  upcoming: events(where: { day_gt: "2020-10-07" }) {
    day
  }
}
```

### DateTime

Hygraph stores Date/DateTime fields as UTC strings, ISO 8601.

Like Date fields, DateTime fields can be filtered using:

| Matches              | Type         | Behavior                |
| -------------------- | ------------ | ------------------------ |
| `[fieldName]_not`    | `DateTime`   | Not this (null accepted) |
| `[fieldName]_in`     | `[DateTime]` | One of                   |
| `[fieldName]_not_in` | `[DateTime]` | Not one of               |
| `[fieldName]_lt`     | `DateTime`   | Less than                |
| `[fieldName]_gt`     | `DateTime`   | Greater than             |
| `[fieldName]_lte`    | `DateTime`   | Less than or equal to    |
| `[fieldName]_gte`    | `DateTime`   | Greater than or equal to |

```graphql
{
  events(where: { start: "2020-10-07T09:00:00+00:00" }) {
    start
  }

  previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {
    start
  }
}
```

### Basic Reference

All relations (except Unions) can be filtered using filters on the fields of the model you are referencing. You can filter where every, some, and none at all match the conditions provided.

| Matches             | Behavior               |
| ------------------- | ----------------------- |
| `[fieldName]_every` | Every reference matches |
| `[fieldName]_some`  | Some references match   |
| `[fieldName]_none`  | No references match     |

For example, you could fetch every post by the provided author name.

```graphql
{
  posts(where: { authors_every: { name_in: ["John", "Simona"] } }) {
    title
    authors {
      name
    }
  }
}
```

<a id="null-references"></a>

#### Null references

It is possible to filter on single, and multi reference fields for when these references are empty.

<Tabs panelHeight={230}>
  <TabsItem label="Where no author connected">

```graphql
{
  posts(where: { author: null }) {
    id
    author {
      id
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Where one author is connected">

```graphql
{
  posts(where: { author: {} }) {
    id
    author {
      id
    }
  }
}
```

  </TabsItem>
</Tabs>

- `[fieldName]_every: {}`: Returns all authors, with or without connected posts
- `[fieldName]_some: {}`: Returns all authors with at least one connected post
- `[fieldName]_none: {}`: Returns all authors that have no posts connected

<Tabs panelHeight={230}>
  <TabsItem label="_none">

```graphql
{
  authors(where: { posts_none: {} }) {
    id
    posts {
      id
    }
  }
}
```

  </TabsItem>
  <TabsItem label="_some">

```graphql
{
  authors(where: { posts_some: {} }) {
    id
    posts {
      id
    }
  }
}
```

  </TabsItem>
  <TabsItem label="_every">

```graphql
{
  authors(where: { posts_every: {} }) {
    id
    posts {
      id
    }
  }
}
```

  </TabsItem>
</Tabs>

### Union reference

Using the `where` filter, you can filter by unions to get into the models and even fields inside of them.

<Tabs panelHeight={350}>
<TabsItem label="Query">
```graphql
query MyQuery {
  # Find posts where the postPageUnion field  has entries connected
  posts(where: { postPageUnion_empty: false }) {
    id
    postPageUnion {
      __typename
      ... on Page {
        id
        path
        updatedAt
      }
    }
  }
}
```
</TabsItem>
<TabsItem label="Response">
```graphql
{
  "data": {
    "posts": [
      {
        "id": "clfuxrsxicbtn0bw80otuqvdc",
        "postPageUnion": [
          {
            "__typename": "Page",
            "id": "clfusno48bgnj0bw8r09tkfmd",
            "path": "home",
            "updatedAt": "2023-03-30T09:51:30.842718+00:00"
          },
          {
            "__typename": "Page",
            "id": "clfusoca3bfb20bw7qq5ppcs7",
            "path": "features",
            "updatedAt": "2023-03-30T10:40:38.541517+00:00"
          },
          {
            "__typename": "Page",
            "id": "clfusouvbbbob0bulri695oa1",
            "path": "404",
            "updatedAt": "2023-03-30T10:53:26.196075+00:00"
          }
        ]
      },
      {
        "id": "clfuzysanci8n0bw7y29vd16n",
        "postPageUnion": [
          {
            "__typename": "Page",
            "id": "clfusouvbbbob0bulri695oa1",
            "path": "404",
            "updatedAt": "2023-03-30T10:53:26.196075+00:00"
          },
          {
            "__typename": "Page",
            "id": "clfusqhb8bbyt0buljnh37oxd",
            "path": "new",
            "updatedAt": "2023-03-30T10:54:59.459294+00:00"
          }
        ]
      }
    ]
  }
}
```
</TabsItem>
</Tabs>

You can combine the `where` filter with the following:

| Matches             | Type      | Behavior                                                                                |
| ------------------- | --------- | ---------------------------------------------------------------------------------------- |
| `[FieldName]_empty` | `Boolean` | If true, it returns every result where the filtered union is not connected / is empty    |
| `[FieldName]_some`  | `Array`   | Matches if the union contains at least one connection to the item provided to the filter |

<Alert theme="info">
- `_empty` and `_some` can be used to query union fields that allow multiple values.

- The filter does not modify the query, but will simply select a subset of entries from the results returned by that query, based on the filter.
</Alert>

<Tabs panelHeight={420}>
<TabsItem label="_empty">
```graphql
query MyQuery { # Find pages where no sections are connected
  pages(where: {sections_empty: true}) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
      }
      ... on GalleryComponent {
        heading
      }
      ... on Testimonial {
        customerName
      }
    }
  }
}
```
</TabsItem>
<TabsItem label="_some">
```graphql
query MyQuery { # Find pages where the testimonial is from Hygraph
  pages(where: {sections_some: {Testimonial: {customerName_contains: "Hygraph"}}}) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
      }
      ... on GalleryComponent {
        heading
      }
      ... on Testimonial {
        customerName
      }
    }
  }
}
```
</TabsItem>
<TabsItem label="Match">
```graphql
# Union reference doesn't allow multiple values
# Find pages where the section union testimonial's customer name contains "Hygraph"
query MyQuery {
  pages(where: {section: {Testimonial: {customerName_contains: "Hygraph"}}}) {
    id
  }
}
```
</TabsItem>
</Tabs>

#### Nested unions

Using filters allows going into the reverse field and getting information from the start model.

<Tabs panelHeight={800}>
<TabsItem label="Query">
```graphql
query MyQuery {
  # Find pages where the Testimonial List contains Hygraph
  pages(
    where: {
      sections_some: {
        # Union relational field
        TestimonialList: {
          # The linked component
          customerList_some: {
            # Basic relational field on the component
            name: "Hygraph" # Field we are filtering for
          }
        }
      }
    }
  ) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
      }
      ... on GalleryComponent {
        heading
      }
      ... on Testimonial {
        customerName
      }
    }
    seo {
      metaTitle
    }
  }
}
```
</TabsItem>
<TabsItem label="Response">
```graphql
{
  "data": {
    "pages": [
      {
        "id": "clfusno48bgnj0bw8r09tkfmd",
        "sections": [
          {
            "__typename": "TextComponent",
            "heading": "Welcome"
          },
          {
            "__typename": "GalleryComponent",
            "heading": "Product Pictures"
          },
          {
            "__typename": "Testimonial",
            "customerName": "Hygraph"
          },
          {
            "__typename": "TestimonialList"
          }
        ],
        "seo": {
          "metaTitle": "Homepage"
        }
      },
      {
        "id": "clfusoca3bfb20bw7qq5ppcs7",
        "sections": [
          {
            "__typename": "TextComponent",
            "heading": "Feature Showcase"
          },
          {
            "__typename": "GalleryComponent",
            "heading": "Pictures"
          },
          {
            "__typename": "TestimonialList"
          }
        ],
        "seo": {
          "metaTitle": "Hygraph"
        }
      }
    ]
  }
}
```
</TabsItem>
</Tabs>

### Basic component

#### Basic component field allows multiple values

All basic component fields that allow multiple values can be filtered using:

| Matches             | Behaviour               |
| ------------------- | ----------------------- |
| `[fieldName]_every` | Every reference matches |
| `[fieldName]_some`  | Some references match   |
| `[fieldName]_none`  | No references match     |

<Tabs panelHeight={200}>
<TabsItem label="_every">
```graphql
query MyQuery { # Finds pages where all Post component paths contain "example"
  pages(where: {posts_every: {path_contains: "example"}}) {
    id
    title
    path
  }
}
```
</TabsItem>
<TabsItem label="_some">
```graphql
query MyQuery { # Finds pages where at least one Post component path contains "example"
  pages(where: {posts_some: {path_contains: "example"}}) {
    id
    title
    path
  }
}
```
</TabsItem>
<TabsItem label="_none">
```graphql
query MyQuery { # Finds pages where none of the Post component paths contain "example"
  pages(where: {posts_none: {path_contains: "example"}}) {
    id
    title
    path
  }
}
```
</TabsItem>
</Tabs>

#### Basic component field doesn't allow multiple values

If the basic component field does not allow multiple values, the `_every`, `_some`, and `_none` filters are unavailable, but you can query for a match as well as for empty components.

<Tabs panelHeight={500}>
<TabsItem label="Empty component">
```graphql
query MyQuery { # Find pages where the seo field is empty (basic component field)
  pages(where: {seo: {}}) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
      }
      ... on GalleryComponent {
        heading
      }
      ... on Testimonial {
        customerName
      }
    }
    seo {
      metaTitle
    }
  }
}
```
</TabsItem>
<TabsItem label="Match">
```graphql
query MyQuery { # Find pages where the Seo components field metatitle contains "Home"
  pages(where: {seo: {metaTitle_contains: "Home"}}) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
      }
      ... on GalleryComponent {
        heading
      }
      ... on Testimonial {
        customerName
      }
    }
    seo {
      metaTitle
    }
  }
}
```
</TabsItem>
</Tabs>

### Modular component

All modular component fields that allow multiple values can be filtered using:

| Matches             | Type      | Behavior                                                                                |
| ------------------- | --------- | ---------------------------------------------------------------------------------------- |
| `[FieldName]_empty` | `Boolean` | If true, it returns every result where the filtered model is empty                       |
| `[FieldName]_some`  | `Array`   | Matches if the model contains at least one connection to the item provided to the filter |

<Tabs panelHeight={200}>
<TabsItem label="_empty">
```graphql
query MyQuery { # Find the id of pages where the sections component is not empty
  pages(where: {sections_empty: false}) {
    id
  }
}

```
</TabsItem>
<TabsItem label="_some">
```graphql
# Find pages that contain at least one connection to the sections component
query MyQuery {
  pages(where: {sections_some: { # Modular component field
    TextComponent: { # The linked component
      heading_contains: "showcase" # The field that we are filtering for
    }
  }
  }) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
        body
      }
    }
  }
}
```
</TabsItem>
<TabsItem label="Match">
```graphql
# Modular component doesn't allow multiple values
# Finds pages where the Section component TextComponent's  heading matches "test"
query MyQuery {
  pages (where: {section: {TextComponent: {heading: "test"}}}) {
    id
  }
}
```
</TabsItem>
</Tabs>

#### Nested components

You can use the above filters to filter data from different levels of nested components as follows:

<Tabs panelHeight={800}>
<TabsItem label="Query">
```graphql
query MyQuery {
  # Find pages where the Testimonial List contains Hygraph
  pages(
    where: {
      sections_some: {
        # Modular component field
        TestimonialList: {
          # The linked component
          customerList_some: {
            # Basic component field on the component
            name: "Hygraph" # Field we are filtering for
          }
        }
      }
    }
  ) {
    id
    sections {
      __typename
      ... on TextComponent {
        heading
      }
      ... on GalleryComponent {
        heading
      }
      ... on Testimonial {
        customerName
      }
    }
    seo {
      metaTitle
    }
  }
}
```
</TabsItem>
<TabsItem label="Response">
```graphql
{
  "data": {
    "pages": [
      {
        "id": "clfusno48bgnj0bw8r09tkfmd",
        "sections": [
          {
            "__typename": "TextComponent",
            "heading": "Welcome"
          },
          {
            "__typename": "GalleryComponent",
            "heading": "Product Pictures"
          },
          {
            "__typename": "Testimonial",
            "customerName": "Hygraph"
          },
          {
            "__typename": "TestimonialList"
          }
        ],
        "seo": {
          "metaTitle": "Homepage"
        }
      },
      {
        "id": "clfusoca3bfb20bw7qq5ppcs7",
        "sections": [
          {
            "__typename": "TextComponent",
            "heading": "Feature Showcase"
          },
          {
            "__typename": "GalleryComponent",
            "heading": "Pictures"
          },
          {
            "__typename": "TestimonialList"
          }
        ],
        "seo": {
          "metaTitle": "Hygraph"
        }
      }
    ]
  }
}
```
</TabsItem>
</Tabs>

### Enumeration

All Enum fields can be filtered by using:

| Matches              | Type                 | Behavior                |
| -------------------- | -------------------- | ------------------------ |
| `[fieldName]_not`    | `EnumerationValue`   | Not this (null accepted) |
| `[fieldName]_in`     | `[EnumerationValue]` | One of                   |
| `[fieldName]_not_in` | `[EnumerationValue]` | Not one of               |

The type of enumeration you can filter by will be the actual Enumeration values defined in your schema.

```graphql
{
  resources(where: { type_in: [Webinar, Ebook] }) {
    id
  }
}
```

<Alert theme="info">
`Webinar` and `Ebook` are Enumeration values for field `type`.
</Alert>

### Taxonomy

All Taxonomy fields can be filtered by using:

| Matches                      | Type                         | Behavior                                                                 |
|-----------------------------|------------------------------|--------------------------------------------------------------------------|
| `[fieldName]_not`           | `TaxonomyNodeWhereInput`     | Not this (null accepted)                                                 |
| `[fieldName]_in`            | `[TaxonomyNodeWhereInput!]`  | One of                                                                   |
| `[fieldName]_not_in`        | `[TaxonomyNodeWhereInput!]`  | Not one of                                                               |
| `[fieldName]_contains_all`  | `[TaxonomyNodeWhereInput!]`  | Contains all specified values                                            |
| `[fieldName]_contains_some` | `[TaxonomyNodeWhereInput!]`  | Contains at least one of the specified values                            |
| `[fieldName]_contains_none` | `[TaxonomyNodeWhereInput!]`  | Contains none of the specified values                                    |
| `[fieldName]_descendants_of`| `[TaxonomyNodeWhereInput!]`  | Returns the specified taxonomy node and all nodes below it (descendants) |

You can filter the taxonomy by the taxonomy node names defined in your schema.

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  productPages(where: {category_descendants_of: {value: "Pants"}}) {
    id
    name
    category {
      value
      path {
        value
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "productPages": [
      {
        "id": "cmdiq25yg02s307ulnc7iuah8",
        "name": "Casual pants",
        "category": {
          "path": [
            {
              "value": "Clothes"
            },
            {
              "value": "Women"
            },
            {
              "value": "Pants"
            },
            {
              "value": "Casual"
            }
          ],
          "value": "Casual"
        }
      },
      {
        "id": "cmdiu3er303kf08upeajplqbq",
        "name": "Formal pants",
        "category": {
          "path": [
            {
              "value": "Clothes"
            },
            {
              "value": "Women"
            },
            {
              "value": "Pants"
            },
            {
              "value": "Formal"
            }
          ],
          "value": "Formal"
        }
      },
      {
        "id": "cmdiu3qse03m607ulk10sg0hu",
        "name": "Jeans",
        "category": {
          "path": [
            {
              "value": "Clothes"
            },
            {
              "value": "Women"
            },
            {
              "value": "Pants"
            },
            {
              "value": "Jeans"
            }
          ],
          "value": "Jeans"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Asset

All Asset fields can be filtered using:

| Matches              | Type            | Behavior                |
| -------------------- | --------------- | ------------------------ |
| `[fieldName]_not`    | `String`        | Not this (null accepted) |
| `[fieldName]_in`     | `[String]`      | One of                   |
| `[fieldName]_not_in` | `[String]`      | Not one of               |
| `[fieldName]_lt`     | `String`        | Less than                |
| `[fieldName]_gt`     | `String`        | Greater than             |
| `[fieldName]_lte`    | `String`        | Less than or equal to    |
| `[fieldName]_gte`    | `String`        | Greater than or equal to |
| `[fieldName]_every`  | _Relation Type_ | Every reference matches  |
| `[fieldName]_some`   | _Relation Type_ | Some references match    |
| `[fieldName]_none`   | _Relation Type_ | No references match      |

Asset fields come with their own [System Fields](/docs/api-reference/schema/system-fields#asset-fields) which you can apply these filters on, as well as any custom fields, or references you add.

You can filter the asset through the reference, or when querying all assets.

For example, we could fetch posts where the `coverImage` field meets the provided criteria on the system field `fileName`:

```graphql
{
  posts(where: { coverImage: { fileName: "image.png" } }) {
    id
    coverImage {
      fileName
    }
  }
}
```

## Combining filters

Just like [combining query arguments](/docs/api-reference/content-api/queries#combining-arguments), it is also possible to combine filters.

```graphql
{
  events(
    where: {
      start_gt: "2020-10-01T09:00:00+00:00"
      start_lt: "2020-10-31T09:00:00+00:00"
      fancyDress: true
      price: 100
    }
  ) {
    start
    fancyDress
    price
  }

  previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {
    start
  }
}
```

## Conditional filters

Hygraph supports conditional filters for your content using `AND`, `NOT` and `OR`. Useful for filtering results based on more than one criteria.

<Alert theme="info">
Conditional filters are a way to logically apply conditions of the applicable filters above. They can also be nested.
</Alert>

| Input Type | Description                                          |
| ---------- | ---------------------------------------------------- |
| `AND`      | Fetch entries that meet both conditions.             |
| `OR`       | Fetch entries that match either condition.           |
| `NOT`      | Fetch all entries where the conditions do not match. |

<Tabs panelHeight={230}>
  <TabsItem label="AND">

```graphql
{
  events(
    where: { AND: [{ start_gte: "2020-10-01" }, { start_lte: "2020-10-31" }] }
  ) {
    id
    start
  }
}
```

  </TabsItem>
  <TabsItem label="OR">

```graphql
{
  events(where: { OR: [{ free: true }, { start_gt: "2020-10-31" }] }) {
    id
    start
  }
}
```

  </TabsItem>
  <TabsItem label="NOT">

```graphql
{
  events(where: { NOT: [{ free: true }, { start_gt: "2020-10-31" }] }) {
    id
    start
  }
}
```

  </TabsItem>
  <TabsItem label="Nested">

```graphql
{
  events(
    where: {
      OR: [
        { AND: [{ start_gte: "2020-10-01" }, { start_lte: "2020-10-31" }] }
        { id: "..." }
      ]
    }
  ) {
    id
    start
  }
}
```

  </TabsItem>
</Tabs>

## Filter by locales

When querying content entries, you can also filter by `locales`:

```graphql
{
  posts(locales: [en]) {
    id
  }
}
```

Learn more about [localization](/docs/api-reference/content-api/localization).

## Filter by stage argument

When querying content entries, you can also filter by `stage`. The stage argument decides what document variation gets returned and searched through. Therefore, if the document does not exist in the stage variation, it gets filtered out.

```graphql
{
  posts(stage: PUBLISHED) {
    id
    stage
  }
}
```

Learn more about [content stages](/docs/api-reference/content-api/content-stages).

## Filter by content stage

Stages work a bit differently in the API than in the UI. In the UI, we use the most intuitive and editor-friendly way of treating filters. So, for instance, if you see a green `PUBLISHED` pill next to an entry, then this entry is only in the `PUBLISHED` stage. However, in the backend, our stages are organized slightly differently. The main difference is that each content entry always exists in `DRAFT`, and other stages are added or removed. For example, an entry that has a green `PUBLISHED` pill in the UI is actually in both `DRAFT` and `PUBLISHED` stages on the API side, and both versions of the entry are identical. If you update the `DRAFT` version but don't publish it, the entry will continue to exist in both stages, but will be marked as blue `PUBLISHED` in the UI.

Stages can be filtered using:

| Matches                  | Behavior                                                                 |
| ------------------------ | ------------------------------------------------------------------------- |
| `documentInStages_every` | All existing stage variations must match the sub-filter                   |
| `documentInStages_some`  | At least one of the existing stage variations must match the sub-filter   |
| `documentInStages_none`  | None of the existing stage variations are allowed to match the sub-filter |

To summarize, like we mentioned before, a document will always exist in the `DRAFT` stage, and they may or may not exist in other published stages such as `PUBLISHED` or for example `QA` - which is a custom content stage that can be published to.

If you, as a user, want to find documents that exist in the `PUBLISHED` stage, you can run the following query:

```graphql
stage: DRAFT
    where: {
			documentInStages_some: {
        stage: PUBLISHED
      }
    }
```

The above `documentInStages_some` allows the user to find documents which exist in a different stage. Let's consider the following 3 documents, which exist in the following stages:

| ID          | STAGES                 |
| ----------- | ---------------------- |
| cldocument1 | [DRAFT, PUBLISHED]     |
| cldocument2 | [DRAFT]                |
| cldocument4 | [DRAFT, PUBLISHED, QA] |

The above query will return documents that also exist in the `PUBLISHED` stage, which are `cldocument1` and `cldocument4`.

However you may have noticed that `cldocument4` also has been published to the `QA` stage - If you have access to custom stages.

Imagine you want to query documents which exist only in one published stage `PUBLISHED`, but not any other publishable stages. In this case the result you want is `cldocument1`. For this we can use `documentInStages_every`.

Keeping in mind that a document entry can exist in multiple stages, the difference between `documentInStages_some` and `documentInStages_every` is that `documentInStages_some` checks if an entry exists in a particular stage, whereas by using `documentInStages_every` we request an entry that exists in only and exactly that stage. So if we use `documentInStages_every` with `PUBLISHED` the query will return results only if the document exists in `PUBLISHED` and no other stage.

You might read this and try a query such as the following:

```graphql

    where: {
			documentInStages_every: {
        stage: PUBLISHED
      }
    }
```

While you are on the right track, this will unfortunately return no results. The reason is that, as we mentioned earlier, every document **always** exists in `DRAFT`, so no document will ever only exist in `PUBLISHED`.

If you try changing the above `PUBLISHED` to `DRAFT`, however, you will get `cldocument2` as a result, as this document only exists in the `DRAFT` stage.

As a workaround for this problem, we can use the `OR` meta filter, by using the following query:

```graphql

    where: {
      documentInStages_every: {
        OR: [
          {
            stage: DRAFT
          },
          {
            stage: PUBLISHED
          }
        ]
      }
    }
```

Since the internal query is that the stage must exist either in `DRAFT` or `PUBLISHED`, the query evaluates to true for both document `cldocument1` and `cldocument2`. It skips `cldocument4`, which is what we want, but we still get `cldocument2` which exists only in `DRAFT`.

We can use the same pattern of using meta filters to filter out the `DRAFT` entry. Let's start by writing this query:

```graphql

    where: {
      NOT: [
        {
          documentInStages_every: {
            stage: DRAFT
          }
        }
      ]
    }
```

As you can see, this query returns any document that does not exist _only_ in `DRAFT`, Which in this case would be `cldocument1` and `cldocument4`. If we were to do an intersection of the results of the above two queries, we would get `cldocument1`, which is the document that we want.

In order to do this, we combine the above two queries to create the following:

```graphql
where: {
      AND: [
			  {
			    documentInStages_every: {
			      OR: [
			        {
			          stage: DRAFT
			        },
			        {
			          stage: PUBLISHED
			        }
			      ]
			    }
			  },
			  {
			    NOT: [
			      {
			        documentInStages_every: {
			          stage: DRAFT
			        }
			      }
			    ]
			  }
			]
    }
```

As you can see above, by using the `AND` meta filter we get the intersection between the two queries above, which returns the `cldocument1` document.

**compareWithParent**

`compareWithParent` allows the comparison of a document with its parent entry using any comparison operators available within it.

At the moment `compareWithParent` is available only inside a `documentInStages_*` filter, and only allows the use of one attribute which is `outdated_to`. This attribute can be found inside the `compareWithParent` filter. The attribute is used to specify if we wish to check whether the child document is outdated compared to the parent document. For example:

```graphql
variousDocuments(
    stage: DRAFT
    where: {
      documentInStages_some: {
        stage: PUBLISHED
        compareWithParent: {
          outdated_to: true
        }
      }
    }
  )
```

In the above example, we enable the filter by setting `outdated_to` to **true** - if it were set to **false**, it would be the same as having the filter omitted entirely. The **true** and **false** values are simply indicators of whether to process the filter in the query.

In the above query, we check if the child `PUBLISHED` version is outdated compared to the `DRAFT` parent version. At the moment, we check if a document is outdated by comparing the `updatedAt` attributes of both the `DRAFT` and `PUBLISHED` versions. If the `DRAFT` has a greater `updatedAt`, that means the document has been modified since it was last published, and is therefore considered outdated.

## JSON filtering

You can filter the data in the `JSON` fields of your Hygraph project using the following filters.

### value_recursive

You can filter the data in your `JSON` fields by using the following `value_recursive` syntax to find exact matches:

```graphql
query for {
  posts(where: { jsonField_value_recursive: "hallo" }) {
    id
    jsonField
  }
}
```

The query above would search the `JSON` fields for an exact match of **"hallo"** on all values, excluding the json keys.

<Alert theme="info">
Using this filter, you can easily filter the content, even if you're not familiar with the `json_path` syntax.
</Alert>

### json_path_exists

You can filter the data in your `JSON` fields by using `json_path_exists` syntax from <Link href="https://www.postgresql.org/docs/current/functions-json.html" target="_blank"><code>PostgreSQL</code></Link>.

To be able to query this content, you need to know the `JSON` structure to navigate through it.

If you're not familiar with the structure, you can query for all content - without passing a filter, or with just a pagination filter depending on number of entries - and look into it. A great way to go about this kind of exploration is using the **API Playground**, where you can type **“json”** then use `ctrl + space` or `command + space` to display all the filters you can use and select one.

<Alert theme="warning">
Please note that if the content data is in a JSON field that allows multiple values, the query will return the complete list.
</Alert>

#### Query syntax examples

Imagine we have the following content data in a `JSON` field which allows multiple values:

```json
"data": {
    "testFieldsModels": [
      {
        "listJsonField": [
          {
            "items": {
              "qty": 24,
              "product": "Diaper"
            },
            "customer": "Lily Bush"
          },
          {
            "items": {
              "qty": 1,
              "product": "Toy Car"
            },
            "customer": "Josh William"
          },
          {
            "items": {
              "qty": null,
              "product": "Headphones"
            },
            "customer": "James Buyer"
          }
        ]
      }
    ]
  },
```

Using the above sample content data, here are some query examples:

- [Query by quantity](/docs/api-reference/content-api/filtering#query-by-quantity)
- [Query by string](/docs/api-reference/content-api/filtering#query-by-string)
- [Query by `null`](/docs/api-reference/content-api/filtering#query-by-null)
- [Query by range](/docs/api-reference/content-api/filtering#query-by-range)

<Alert theme="warning">
Please note that in the query examples below, we escape the quotes with a backslash, like this `\”`. This is because the query is already inside double quotes, so any additional quotes require this format.
</Alert>

&nbsp;
<a id="query-by-quantity"></a>

**Query by quantity**

You can use `"$[*].** ? (@ > N)”` to filter all values all for integers above a certain number. Just replace `N` with the number of your choice.

```graphql
query for {
  testFieldsModels(
    where: { listJsonField_json_path_exists: "$[*].items.qty ? (@ > 5)" }
  ) {
    listJsonField
  }
}
```

The above query example returns products with a quantity greater than 5.

<Alert theme="info" title="Pro Tip">
**You can use:**

- `>`: Greater than
- `>=`: Greater than or equal to
- `<`: Less than
- `<=`: Less than or equal to
</Alert>

&nbsp;
<a id="query-by-string"></a>

**Query by string**

You can use `"$.** ? (@ == \"String\")”` to filter all values all for the matching string:

```graphql
query for {
  testFieldsModels(
    where: {
      listJsonField_json_path_exists: "$.items.product ? (@ == \"Toy Car\")"
    }
  ) {
    listJsonField
  }
}
```

The above query example returns products with the name **“Toy Car”**.

&nbsp;
<a id="query-by-null"></a>

**Query by `null`**

You can use `"$[*].** ? (@ == null)”` to filter all values all for null.

```graphql
query for {
  testFieldsModels(
    where: { listJsonField_json_path_exists: "$[*].items.qty ? (@ == null)" }
  ) {
    listJsonField
  }
}
```

The above query example returns items where quantity (qty) = `null`.

&nbsp;
<a id="query-by-range"></a>

**Query by range**

You can use `"$[*].** ? (@ > N && @ < N)”` to filter all values all for a range of numbers. Just replace `N` with the numbers of your choice.

```graphql
query for {
  testFieldsModels(
    where: {
      listJsonField_json_path_exists: "$[*].items.qty ? (@ > 1 && @ < 5)"
    }
  ) {
    listJsonField
  }
}
```

The above query example returns items with a quantity between 1 and 5.

<Alert theme="info" title="Pro Tip">
**You can use:**

- `>`: Greater than
- `>=`: Greater than or equal to
- `<`: Less than
- `<=`: Less than or equal to
</Alert>


---
# Headers

Source: https://hygraph.com/docs/api-reference/content-api/headers

## Overview

HTTP headers are a set of key-value pairs included in HTTP requests. They are essential for communicating extra information between the client (you) and the server. 

When making GraphQL queries over HTTP, headers are typically used to send important details, like authentication info, content type information, or custom information needed by the server.

Think of HTTP headers as “metadata” for your request, as they carry information about the request itself rather than the actual query content. 

Each header has a name (like `"Authorization"`) and a value (like `"Bearer YOUR_TOKEN_HERE"`).

For example:

```
Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json
```

## HTTP headers in GraphQL

These are the most commonly used headers in GraphQL:

- **Authorization**: You need an authorization token for secure API access in Hygraph. You'll use **HTTP headers** to pass authentication tokens, specifically the `Authorization` header with a **Bearer token**. This process ensures that only authorized users or systems can access your data.
    - For example: `Authorization: Bearer YOUR_TOKEN_HERE`
- **Content-Type**: This header tells the server what format the request body is in. In GraphQL, it's usually JSON.
    - For example: `Content-Type: application/json`
- **Custom Headers**: If you need to send any specific info to the server, you can add your own headers. The [custom headers](/docs/api-reference/content-api/headers#custom-headers) shown in this document, are headers that Hygraph specifically uses to control aspects related to how the data should be fetched. While they follow the general structure of HTTP headers, they are unique to Hygraph's API and not standard HTTP headers like `Authorization` or `Content-Type`.
    - For example: `gcms-stage: DRAFT`

### Add headers to a GraphQL query

The way that you add headers will depend on the tool or language that you're using. Here's how you'd typically add headers in two common ways: using `cURL` (a command-line tool) and `JavaScript` (fetch API).

Example with `cURL`:

```bash
curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -d '{"query": "{ yourQueryHere }"}' \
     https://your-graphql-api.com/graphql
```

Example with `JavaScript`:

```jsx
fetch("https://your-graphql-api.com/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN_HERE"
  },
  body: JSON.stringify({
    query: "{ yourQueryHere }"
  })
})
  .then(response => response.json())
  .then(data => console.log(data));
```

<Alert theme="info" title="Pro Tip">

The `headers` object shown in of both examples above is where we specify the `HTTP` headers. Each header will let the server understand the context of your request.

</Alert>

## Custom headers

 You can use headers as a global way to send more specific requests to our API. While you could use parameters for this, it is generally easier to dynamically change headers than parameters in a query.

This is where you add headers in the API Playground:

![Headers in the API Playground](/images/docs/api-reference/content-api/headers-api-playground.png)

### gcms-locales

This header works in the same way as [using the query input for locales](/docs/api-reference/content-api/localization#fallback-locales).

You can pass the `gcms-locales` header for localized content with your required locales. It is just another way besides the query param to decide which locales a query should return. Basically, the placement is different - header vs. query - but the result is the same. Using one or the other mostly comes down to the developer's preference.

**Why use `gmcs-locales` instead of the query param then?**

To keep queries exactly the same across different environments - production, development, etc. - and then instead of passing the param to the query, you use the header.

In some specific cases passing headers could be easier than putting the params in the query itself.

Example usage `'gcms-locales': 'rb, de, en'`:

```js
const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'gcms-locales': 'rb, de, en',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-hygraph-endpoint>', {
  method: 'POST',
  headers,
  body,
});
```

You can also pass an array of locales to `gcms-locales` to define your fallback preference.

### gcms-stage

This header works in the same way as [using the stage input on a query](/docs/api-reference/content-api/queries#fetching-stages).

You can pass the `gcms-stage` header to specify the stage of your content. It is just another way besides the query param to decide which stage a query should return. Basically, the placement is different - header vs. query - but the result is the same. Using one or the other mostly comes down to the developer's preference.

**Why use `gcms-stage` instead of the query param then?**

To keep queries exactly the same across different environments - production, development, etc. - and then instead of passing the param to the query, you use the header.

In some specific cases passing headers could be easier than putting the params in the query itself.

Example usage `'gcms-stage': 'DRAFT'`:

```js
const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'gcms-stage': 'DRAFT',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-hygraph-endpoint>', {
  method: 'POST',
  headers,
  body,
});
```

### hyg-stale-if-error

This header for the [High performance endpoint](/docs/api-reference/basics/caching#stale-if-error) lets you set `stale-if-error` on a per query basis.

This cache header can be used to fine-tune our default caching behavior. For instance, we could use it to make sure we return stale data on errors for much longer.

The need to use this header highly depends on the use-case and whether it's important to always get fresh data or to always get data, no matter if stale or new.

Example usage `'hyg-stale-if-error': '21600'`:

```js
const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'hyg-stale-if-error': '21600',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-hygraph-endpoint>', {
  method: 'POST',
  headers,
  body,
});
```

The values are in seconds. The default value is `86400`, but this can be adjusted **on dedicated clusters** if needed.

<Alert theme="info" title="Pro Tip">
This is only available on the <b>High performance</b> endpoint.

The default `Stale-if-error` for all **shared clusters** is 86400s (1 day). This value is customizable for **dedicated clusters**.

To check what your current default is, send a request to the [high-performance endpoint](/docs/api-reference/basics/caching#high-performance-endpoint) and check the response headers called `gcms-origin-cache-control`. On a shared cluster, the value of the response header would be similar to this `s-maxage=31536000, stale-if-error=86400, stale-while-revalidate=0`.
</Alert>

### hyg-stale-while-revalidate

This header for the [High performance endpoint](/docs/api-reference/basics/caching#stale-while-revalidate) lets you set `stale-while-revalidate` on a per query basis.

This cache header can be used to fine-tune our default caching behavior. For instance, we could use it to make sure we return stale data while the cache is revalidating.

The need to use this header highly depends on the use-case and whether it's important to always get fresh data or to always get data, no matter if stale or new.

Example usage `'hyg-stale-while-revalidate': '27'`:

```js
const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'hyg-stale-while-revalidate': '27',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-hygraph-endpoint>', {
  method: 'POST',
  headers,
  body,
});
```

The values are in seconds. The default value is `0`, but this can be adjusted **on dedicated clusters** if needed.

<Alert theme="info" title="Pro Tip">
This is only available on the <b>High performance</b> endpoint.

The default `stale-while-revalidate` for our **shared clusters** is `0`. This value is customizable for **dedicated clusters**.

To check what your current default is, send a request to the [high-performance endpoint](/docs/api-reference/basics/caching#high-performance-endpoint) and check the response headers called `gcms-origin-cache-control`. On a shared cluster, the value of the response header would be similar to this `s-maxage=31536000, stale-if-error=86400, stale-while-revalidate=0`.
</Alert>

### x-debug-complexity

You can use this header to enable complexity debugging, so the [complexity tree](/docs/api-reference/basics/query-complexity#complexity-tree-json-output) is returned.

The possible values are `true` & `false`.

Example usage `'x-debug-complexity': 'true'`:

```js
const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'x-debug-complexity': 'true',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-hygraph-endpoint>', {
  method: 'POST',
  headers,
  body,
});
```


---
# Localization

Source: https://hygraph.com/docs/api-reference/content-api/localization

## Overview

Hygraph boasts a flexible localization API that you can use to publish content for all or specific locales in your project.

<Alert theme="warning">
**Locales are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.
</Alert>

Localized content can be managed through the Hygraph UI, or via GraphQL mutations.

## Localizing fields

When adding a field that can be localized inside the schema builder, such as a string, mark the field as can be localized, and you will be able to perform all of the localization queries, and mutations outlined below.

![Hygraph Localize Fields](/images/docs/api-reference/content-api/localize-field.png)

The model will be updated to contain additional [localized system fields](/docs/api-reference/schema/system-fields#localization-fields) that you can use to fetch localized content.

## Fetching localized content

Fetching localized content is done by [fetching content](/docs/api-reference/content-api/queries) the same way you are used to. For example, a product model containing localized fields can be queried like so:

```graphql
{
  product(where: { id: "..." }) {
    name
  }
  products {
    name
  }
}
```

The above will return the default locale values for the fields requested.

### Default locale

As shown as above, queried content will always return the default locale, unless told otherwise.

You can set the default locale inside `Settings > Locales`.

![Hygraph default locale](/images/docs/api-reference/content-api/default-locale.png)

### Fallback locale(s)

Locales will be returned in the order they are requested, from left to right.

In this example, we will request products with the locales `en`, and `de`.

<Tabs panelHeight={200}>
  <TabsItem label="Request">

```graphql
{
  products(locales: [en, de]) {
    id
    locale
    name
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "id": "ck3ee0ltu3kfn0b73wbslopia",
        "locale": "en",
        "name": "Unisex Long Sleeve Tees"
      },
      {
        "id": "ck3itjds7hnwo0b66au5rkvm9",
        "locale": "en",
        "name": "Snapback"
      },
      {
        "id": "ck3oqti2stn5o0b20ogmpwxer",
        "locale": "en",
        "name": "Unisex Zip Hoodie"
      },
      {
        "id": "ck3shntzy1xxw0b324jfxcjtl",
        "locale": "en",
        "name": "Mug"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### HTTP header

You can pass the `gcms-locales` header when localized content with your required locales.

```js
const fetch = require('cross-fetch');

const headers = {
  'Content-Type': 'application/json',
  'gcms-locales': 'en',
};

const body = JSON.stringify({ query: '{ products { name } }' });

const { products } = await fetch('<your-hygraph-endpoint>', {
  method: 'POST',
  headers,
  body,
});
```

You can also pass an array of locales to `gcms-locales` to define your fallback preference.

### All localizations

Whether you're fetching a [single content entry](/docs/api-reference/content-api/queries#fetching-a-single-entry), or [multiple](/docs/api-reference/content-api/queries#fetching-multiple-entries), you can fetch all `localizations` of that entry.

<Tabs panelHeight={280}>
  <TabsItem label="Request">

```graphql
{
  products {
    id
    name
    localizations {
      id
      name
      locale
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "id": "ck3ee0ltu3kfn0b73wbslopia",
        "name": "Unisex Long Sleeve Tees",
        "localizations": [
          {
            "id": "ck3ee0ltu3kfn0b73wbslopia",
            "name": "Unisex Longsleeve",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3itjds7hnwo0b66au5rkvm9",
        "name": "Snapback",
        "localizations": [
          {
            "id": "ck3itjds7hnwo0b66au5rkvm9",
            "name": "Cap",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3oqti2stn5o0b20ogmpwxer",
        "name": "Unisex Zip Hoodie",
        "localizations": [
          {
            "id": "ck3oqti2stn5o0b20ogmpwxer",
            "name": "Unisex Hoodie",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3shntzy1xxw0b324jfxcjtl",
        "name": "Mug",
        "localizations": [
          {
            "id": "ck3shntzy1xxw0b324jfxcjtl",
            "name": "Tasse mit Print",
            "locale": "de"
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

Since the root graphql type returns the default locale `en` values, you'll notice the `localizations` response above returns just the `de` content entries.

Pass `includeCurrent: true` inside the `localizations` query arguments to include the default `en` locale.

<Tabs panelHeight={280}>
  <TabsItem label="Request">

```graphql
{
  products {
    id
    name
    localizations(includeCurrent: true) {
      id
      name
      locale
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "id": "ck3ee0ltu3kfn0b73wbslopia",
        "name": "Unisex Long Sleeve Tees",
        "localizations": [
          {
            "id": "ck3ee0ltu3kfn0b73wbslopia",
            "name": "Unisex Long Sleeve Tees",
            "locale": "en"
          },
          {
            "id": "ck3ee0ltu3kfn0b73wbslopia",
            "name": "Unisex Longsleeve",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3itjds7hnwo0b66au5rkvm9",
        "name": "Snapback",
        "localizations": [
          {
            "id": "ck3itjds7hnwo0b66au5rkvm9",
            "name": "Snapback",
            "locale": "en"
          },
          {
            "id": "ck3itjds7hnwo0b66au5rkvm9",
            "name": "Cap",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3oqti2stn5o0b20ogmpwxer",
        "name": "Unisex Zip Hoodie",
        "localizations": [
          {
            "id": "ck3oqti2stn5o0b20ogmpwxer",
            "name": "Unisex Zip Hoodie",
            "locale": "en"
          },
          {
            "id": "ck3oqti2stn5o0b20ogmpwxer",
            "name": "Unisex Hoodie",
            "locale": "de"
          }
        ]
      },
      {
        "id": "ck3shntzy1xxw0b324jfxcjtl",
        "name": "Mug",
        "localizations": [
          {
            "id": "ck3shntzy1xxw0b324jfxcjtl",
            "name": "Mug",
            "locale": "en"
          },
          {
            "id": "ck3shntzy1xxw0b324jfxcjtl",
            "name": "Tasse mit Print",
            "locale": "de"
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="warning">
This will return all locales where values present. If nothing is found, the default locale will be returned.
</Alert>

## Mutating localized content

Just like you can query localized content, you can also create, update, upsert, and delete localized content using the [Mutations API](/docs/api-reference/content-api/mutations).

Let's continue with the products model in our examples below. We can use the [auto-generated mutations](/docs/api-reference/content-api/mutations#auto-generated-mutations) for modifying the locales for each entry.

### Create a localization

```graphql
mutation {
  updateProduct(
    where: { id: "..." }
    data: {
      localizations: {
        create: { locale: de, data: { name: "Tasse mit Print" } }
      }
    }
  ) {
    id
  }
}
```

<Alert theme="info">
You'll notice above we are using the `update[Model]` mutation to "create" a locale. This is because the existing entry is the default locale, and you can create additional localized content for fields on that entry.
</Alert>

You can also pass an array of localizations for locales that aren't your projects default. For example, here we create localizations for both `de`, and `es`.

```graphql
mutation {
  updateProduct(
    where: { id: "..." }
    data: {
      localizations: {
        create: [
          { locale: de, data: { name: "Tasse mit Print" } }
          { locale: es, data: { name: "Taza con estampado" } }
        ]
      }
    }
  ) {
    id
  }
}
```

The examples here assume you already have a product that you can update. It is possible to create a new entry, with the base locale, and the localized content via `localizations` at the same time:

```graphql
mutation {
  createProduct(
    data: {
      name: "Mug"
      localizations: {
        create: [
          { locale: de, data: { name: "Tasse mit Print" } }
          { locale: es, data: { name: "Taza con estampado" } }
        ]
      }
    }
  ) {
    id
    localizations(includeCurrent: true) {
      title
    }
  }
}
```

### Update a localization

```graphql
mutation {
  updateProduct(
    where: { id: "..." }
    data: { localizations: { update: { locale: en, data: { name: "Mug" } } } }
  ) {
    id
  }
}
```

### Upsert a localization

Just like you can create, or update content entries by unique filters, you can either also upsert localizations. Simply pass the `locale` you want to update, or create if it does not exist.

```graphql
mutation {
  createProduct(
    where: { id: "..." }
    data: {
      localizations: {
        upsert: {
          locale: de
          create: { name: "Tasse mit Print" }
          update: { name: "Tasse mit Print" }
        }
      }
    }
  ) {
    id
  }
}
```

### Delete a localization

To delete a localization, you need to use an update mutation, like so:

```graphql
mutation {
  updatePost(
    where: {
      id: "..."
    }
    data: {
      localizations: {
        delete: [de]
      }
    }
  )
}
```

<Alert theme="warning">
It is not possible to delete the default localization.
</Alert>

---
# Mutations

Source: https://hygraph.com/docs/api-reference/content-api/mutations

Your project endpoint exposes GraphQL mutations you can use to modify the contents of your project. The mutations API allows you to interact with content ouside of the <Link href="https://app.hygraph.com" target="_blank">Hygraph UI</Link> using GraphQL.

<Alert theme="warning">
It's not recommended you enable Public API Permissions for mutations, but instead use a [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens) for mutating data.
</Alert>

## Auto-generated mutations

When a new model is added to your project, so are custom GraphQL mutations.

For example, if you created a `Product` model, these mutations would also be generated inside your GraphQL schema:

- `createProduct`
- `updateProduct`
- `deleteProduct`
- `upsertProduct`
- `publishProduct`
- `unpublishProduct`
- `updateManyProductsConnection`
- `deleteManyProductsConnection`
- `publishManyProductsConnection`
- `unpublishManyProductsConnection`

All of these mutations accept input types that are specific to your projects GraphQL schema.

## Create entries

When creating new content entries, the `data` argument will have an associated input type that is specific to your content model.

For example, if your project contains the model `Product`, you will have:

| Mutation        | Argument | Input Type            |
| --------------- | -------- | --------------------- |
| `createProduct` | `data`   | `ProductCreateInput!` |

<Tabs panelHeight={220}>
  <TabsItem label="Request">

```graphql
mutation {
  createProduct(data: { name: "Face Mask", slug: "face-mask", price: 1000 }) {
    id
    name
    slug
    price
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "createProduct": {
      "id": "ckgcd5hzc01wd0a446vd3kqrs",
      "name": "Face Mask",
      "slug": "face-mask",
      "price": 1000
    }
  }
}
```

  </TabsItem>
</Tabs>

The `id` is a [default system field](/docs/api-reference/schema/system-fields#default-model-fields) that is automatically generated for all new entries.

## Update entries

When updating single content entry, you must specify the unique `where` criteria of which you want to update, as well as the new `data`.

For example, if your project contains the model `Product`, you will have:

| Argument | Input Type                 |
| -------- | -------------------------- |
| `where`  | `ProductWhereUniqueInput!` |
| `data`   | `ProductUpdateInput!`      |

<Tabs panelHeight={260}>
  <TabsItem label="Request">

```graphql
mutation {
  updateProduct(
    where: { id: "ckgcd5hzc01wd0a446vd3kqrs" }
    data: { price: 100 }
  ) {
    id
    name
    price
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "updateProduct": {
      "id": "ckgcd5hzc01wd0a446vd3kqrs",
      "name": "Face Mask",
      "price": 100
    }
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="info">
You can also update any unique field on your model.
</Alert>

## Upsert entries

The upsert mutation allows you to create, or update a content entry based on whether the unique `where` values exist.

For example, if your project contains the model `Product`, you will have:

| Argument            | Input Type                 |
| ------------------- | -------------------------- |
| `where`             | `ProductWhereUniqueInput!` |
| `upsert`            | `ProductUpsertInput!`      |
| `upsert` > `create` | `ProductCreateInput!`      |
| `upsert` > `update` | `ProductUpdateInput!`      |

<Alert theme="info">
You must provide both `create`, and `update` to the `upsert` argument.
</Alert>

<Tabs panelHeight={340}>
  <TabsItem label="Request">

```graphql
mutation {
  upsertProduct(
    where: { slug: "face-mask" }
    upsert: {
      create: { name: "Face Mask", slug: "face-mask", price: 1000 }
      update: { name: "Face Mask", slug: "face-mask", price: 1000 }
    }
  ) {
    id
    name
    slug
    price
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "upsertProduct": {
      "id": "ckgcf201401cz0a56wyon4fj8",
      "name": "Face Mask",
      "slug": "face-mask",
      "price": 1000
    }
  }
}
```

  </TabsItem>
</Tabs>

## Delete entries

Similar to updating, and upserting entries, you can specify using `where` the entries you want to delete.

For example, if your project contains the model `Product`, you will have:

| Argument | Input Type                 |
| -------- | -------------------------- |
| `where`  | `ProductWhereUniqueInput!` |

<Tabs panelHeight={220}>
  <TabsItem label="Request">

```graphql
mutation {
  deleteProduct(where: { id: "..." }) {
    id
    name
    slug
    price
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "deleteProduct": {
      "id": "ckgcf201401cz0a56wyon4fj8",
      "name": "Face Mask",
      "slug": "face-mask",
      "price": 1000
    }
  }
}
```

  </TabsItem>
</Tabs>

## Nested mutations

- `create`: Create and relate entries
- `connect`: Connect additional existing entries by unique field
- `update`: Update the connected entries
- `upsert`: Create or update connected entries
- `disconnect`: Disconnect connected relations by unique field
- `delete`: Delete all connected entries
- `set`: Override all connected entries

### Create

<Tabs panelHeight={900}>
  <TabsItem label="create">

```graphql
mutation createOneRelation {
  createProduct(
    data: {
      name: "Test"
      slug: "test"
      price: 1000
      category: { create: { name: "Accessories", slug: "accessories" } }
    }
  ) {
    id
    name
    category {
      name
    }
  }
}

mutation createManyRelations {
  createProduct(
    data: {
      name: "Test"
      slug: "test"
      price: 1000
      category: {
        create: [
          { name: "Accessories", slug: "accessories" }
          { name: "...", slug: "..." }
        ]
      }
    }
  ) {
    id
    name
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="connect">

```graphql
mutation createAndConnectOne {
  createProduct(
    data: {
      name: "Test"
      slug: "test"
      price: 1000
      category: { connect: { slug: "accessories" } }
    }
  ) {
    id
    name
    category {
      name
    }
  }
}

mutation createAndConnectMany {
  createProduct(
    data: {
      name: "Test"
      slug: "test"
      price: 1000
      categories: { connect: [{ slug: "accessories" }, { id: "..." }] }
    }
  ) {
    id
    name
    category {
      name
    }
  }
}
```

  </TabsItem>
</Tabs>

### Update

<Tabs panelHeight={300}>
  <TabsItem label="create">

```graphql
mutation {
  updateProduct(
    where: { id: "..." }
    data: { category: { create: { name: "Accessories", slug: "accessories" } } }
  ) {
    id
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="update">

```graphql
mutation {
  updateProduct(
    where: { id: "..." }
    data: {
      category: {
        update: {
          where: { slug: "accessories" }
          data: { name: "All Accessories" }
        }
      }
    }
  ) {
    id
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="upsert">

```graphql
mutation {
  updateProduct(
    where: { id: "..." }
    data: {
      category: {
        upsert: {
          where: { slug: "accessories" }
          data: {
            create: { name: "Accessories", slug: "accessories" }
            update: { name: "Accessories", slug: "accessories" }
          }
        }
      }
    }
  ) {
    id
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="connect">

```graphql
mutation updateAndConnectOne {
  updateProduct(
    where: { id: "..." }
    data: { category: { connect: { id: "..." } } }
  ) {
    id
    category {
      name
    }
  }
}

mutation updateAndConnectMany {
  updateProduct(
    where: { id: "..." }
    data: {
      categories: {
        connect: [{ where: { id: "..." } }, { where: { id: "..." } }]
      }
    }
  ) {
    id
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="disconnect">

```graphql
mutation disconnectOneSide {
  updateProduct(
    where: { id: "..." }
    data: { category: { disconnect: true } }
  ) {
    id
    category {
      name
    }
  }
}

mutation disconnectManySide {
  updateProduct(
    where: { id: "..." }
    data: { categories: { disconnect: [{ id: "..." }, { id: "..." }] } }
  ) {
    id
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="delete">

```graphql
mutation {
  updateProduct(where: { id: "..." }, data: { category: { delete: true } }) {
    id
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="set">

```graphql
mutation {
  updateCategory(
    where: { id: "..." }
    data: { products: { set: [{ slug: "..." }, { id: "..." }] } }
  ) {
    name
    products {
      name
    }
  }
}
```

  </TabsItem>
</Tabs>

## Insert at position

When inserting related entries, you can `connect` entries at a given position. The position of entries reflects that [fetching relations](/docs/api-reference/content-api/queries#fetching-relations).

The `position` input accepts the following values:

| Field    | Type      | Definition                                       |
| -------- | --------- | ------------------------------------------------ |
| `before` | `ID`      | The ID of the entry you want to insert before    |
| `after`  | `ID`      | The ID of the entry you want to insert after     |
| `start`  | `Boolean` | Set to `true` if you want to insert at the start |
| `end`    | `Boolean` | Set to `true` if you want to insert at the end   |

<Alert theme="info">
You must only provide one of these values.
</Alert>

#### Before

```graphql
mutation {
  updateAuthor(
    where: { id: "..." }
    data: { posts: { connect: { position: { before: "..." } } } }
  ) {
    id
  }
}
```

#### After

```graphql
mutation {
  updateAuthor(
    where: { id: "..." }
    data: { posts: { connect: { position: { after: "..." } } } }
  ) {
    id
  }
}
```

#### Start

```graphql
mutation {
  updateAuthor(
    where: { id: "..." }
    data: { posts: { connect: { position: { start: true } } } }
  ) {
    id
  }
}
```

#### End

```graphql
mutation {
  updateAuthor(
    where: { id: "..." }
    data: { posts: { connect: { position: { end: true } } } }
  ) {
    id
  }
}
```

## Publishing content mutations

Hygraph automatically generates publish, and unpublish mutations for each of your content models, including the asset model.

Learn more about [publishing and unpublishing content](/docs/api-reference/content-api/content-stages).

## Batch mutations

Hygraph supports batch mutations that can be applied to "many" entries at once. You may wish to update, or delete many entries at once that fit given criteria.

Batch mutations comply with the [Relay connection type](/docs/api-reference/content-api/queries#fetching-with-relay) specification.

### Update many

To update many entries at once, you must use the `updateMany[Model]Connection` mutation. You can use [where](/docs/api-reference/content-api/filtering), or [pagination](/docs/api-reference/content-api/pagination) filters to set the criteria you wish to update.

| Argument | Input Type              | Description                                                                                     |
| -------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `where`  | `ProductManyWhereInput` | [Filtering](/docs/api-reference/content-api/filtering) criteria for entries you want to update. |
| `data`   | `CreateInput!`          | An object that specifies the data you'd like to update matching entries with.                   |
| `first`  | `Int`                   | Seek forwards from end of result set.                                                           |
| `last`   | `Int`                   | Seek backwards from start of result set.                                                        |
| `skip`   | `Int`                   | Skip result set by given amount.                                                                |
| `before` | `ID`                    | Seek backwards before specific ID.                                                              |
| `after`  | `ID`                    | Seeks forwards after specific ID.                                                               |

<Alert theme="warning">
If you do not pass any filters, then the first 10 entries will be updated. See [Pagination](/docs/api-reference/content-api/pagination) for updating pages.
</Alert>

For example, let's update all products where `featured: true`, to be `featured: false`.

<Tabs panelHeight={300}>
  <TabsItem label="Request">

```graphql
mutation {
  updateManyProductsConnection(
    where: { featured: true }
    data: { featured: false }
  ) {
    edges {
      node {
        featured
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "updateManyProductsConnection": {
      "edges": [
        {
          "node": {
            "featured": true
          }
        },
        {
          "node": {
            "featured": true
          }
        },
        {
          "node": {
            "featured": true
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

### Delete many

To delete many entries at once, you must use the `deleteMany[Model]Connection` mutation. You can use [where](/docs/api-reference/content-api/filtering), or [pagination](/docs/api-reference/content-api/pagination) filters to set the criteria you wish to delete.

| Argument | Input Type              | Description                                                                                     |
| -------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `where`  | `ProductManyWhereInput` | [Filtering](/docs/api-reference/content-api/filtering) criteria for entries you want to delete. |
| `first`  | `Int`                   | Seek forwards from end of result set.                                                           |
| `last`   | `Int`                   | Seek backwards from start of result set.                                                        |
| `skip`   | `Int`                   | Skip result set by given amount.                                                                |
| `before` | `ID`                    | Seek backwards before specific ID.                                                              |
| `after`  | `ID`                    | Seeks forwards after specific ID.                                                               |

<Alert theme="warning">
If you do not pass any filters, then the first 10 entries will be deleted. See [Pagination](/docs/api-reference/content-api/pagination) for updating pages.
</Alert>

<Tabs panelHeight={250}>
  <TabsItem label="Request">

```graphql
mutation {
  deleteManyProductsConnection(where: { featured: true }) {
    edges {
      node {
        id
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "deleteManyProductsConnection": {
      "edges": [
        {
          "node": {
            "id": "ckdt46o2w029u0156q124e0x4"
          }
        },
        {
          "node": {
            "id": "ckdt47uio02al01044grc4ehf"
          }
        },
        {
          "node": {
            "id": "ckdt4c9gw02cu01026bzkok1b"
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

### Publish many

Just like you can [publish content](#publishing-content-mutations), you can also batch publish.

| Argument | Input Type                | Description                                                                               |
| -------- | ------------------------- | ----------------------------------------------------------------------------------------- |
| `where`  | `ProductManyWhereInput`   | [Filtering](/docs/api-reference/content-api/filtering) criteria finding entries.          |
| `from`   | `Stage = DRAFT`           | The [content stage](/docs/api-reference/content-api/content-stages) to find entries from. |
| `to`     | `[Stage!]! = [PUBLISHED]` | The target published [content stage](/docs/api-reference/content-api/content-stages).     |
| `first`  | `Int`                     | Seek forwards from end of result set.                                                     |
| `last`   | `Int`                     | Seek backwards from start of result set.                                                  |
| `skip`   | `Int`                     | Skip result set by given amount.                                                          |
| `before` | `ID`                      | Seek backwards before specific ID.                                                        |
| `after`  | `ID`                      | Seeks forwards after specific ID.                                                         |

For example, we could publish the first 5 products to the `PUBLISHED` stage.

<Tabs panelHeight={250}>
  <TabsItem label="Request">

```graphql
mutation {
  publishManyProductsConnection(first: 5, to: PUBLISHED) {
    edges {
      node {
        id
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "publishManyProductsConnection": {
      "edges": [
        {
          "node": {
            "id": "ckdt46o2w029u0156q124e0x4"
          }
        },
        {
          "node": {
            "id": "ckdt47uio02al01044grc4ehf"
          }
        },
        {
          "node": {
            "id": "ckdt4c9gw02cu01026bzkok1b"
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

### Unpublish many

Just like you can batch publish, you can also batch unpublish.

| Argument | Input Type                | Description                                                                                   |
| -------- | ------------------------- | --------------------------------------------------------------------------------------------- |
| `where`  | `ProductManyWhereInput`   | [Filtering](/docs/api-reference/content-api/filtering) criteria for entries you want to find. |
| `stage`  | `Stage = DRAFT`           | The [content stage](/docs/api-reference/content-api/content-stages) to find entries in.       |
| `to`     | `[Stage!]! = [PUBLISHED]` | The target published [content stage](/docs/api-reference/content-api/content-stages).         |
| `first`  | `Int`                     | Seek forwards from end of result set.                                                         |
| `last`   | `Int`                     | Seek backwards from start of result set.                                                      |
| `skip`   | `Int`                     | Skip result set by given amount.                                                              |
| `before` | `ID`                      | Seek backwards before specific ID.                                                            |
| `after`  | `ID`                      | Seeks forwards after specific ID.                                                             |

<Tabs panelHeight={250}>
  <TabsItem label="Request">

```graphql
mutation {
  unpublishManyProductsConnection(stage: PUBLISHED) {
    edges {
      node {
        id
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "unpublishManyProductsConnection": {
      "edges": [
        {
          "node": {
            "id": "ckdt46o2w029u0156q124e0x4"
          }
        },
        {
          "node": {
            "id": "ckdt47uio02al01044grc4ehf"
          }
        },
        {
          "node": {
            "id": "ckdt4c9gw02cu01026bzkok1b"
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

## Localized content mutations

Depending on whether or not you have localized fields in your schema, you will be able to mutate each of the localized content entries.

Learn more about [mutating localized content](/docs/api-reference/content-api/localization#mutating-localized-content).

## Conditional fields

When you create a field via mutation, you can use `visibilityCondition` **to set conditional visibility** for it:

```graphql
mutation CreateConditionalRichTextField {
  createSimpleField(
    data: {type: RICHTEXT, parentId: "6b0ce6afe6c74bd196948b3eb28501a3", apiId: "conditionalRichtext", displayName: "Conditional Richtext", isRequired: false, isUnique: false, isList: false, isLocalized: false, visibilityCondition: {baseField: "d1798ceb369c4aad98d6bd286b879109", operator: IS, booleanValue: true}}
  ) {
    migration {
      id
    }
  }
}
```
In this example `parentId` is an ID of a model or a component, and `baseField` is an ID of the field used for condition, in this case a boolean field.

**To create an entry** for an existing model and set a visibility condition:

<Tabs panelHeight={250}>
  <TabsItem label="Mutation">

```graphql
mutation {
  createSubsidiaries(
    data: {name: "New location", publicHoliday: true, publicHolidayMessage: "Today is a public holiday!", slug: "new-location", information: "This is a new subsidiary"}
  ) {
    id
    information
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "createSubsidiaries": {
      "id": "cm1kneaip038b07vuy7sdx31w",
      "information": "This is a new subsidiary"
    }
  }
}
```

  </TabsItem>
</Tabs>

In this example, `Subsidiaries` is a model that contains a `publicHoliday` boolean which, when set to `true`, makes the `publicHolidayMessage` field visible.

When you go to the content editor and access the edit view of this content entry, `publicHolidayMessage` will be visible:

![Conditional visibility in the UI](/images/docs/api-reference/content-api/conditional-visibility-ui.png)

<Alert theme="info">

To set a condition, the model or component needs to have a boolean or enumeration field.

Check out our [conditional fields documentation](/docs/developer-guides/schema/conditional-fields) to learn more.

</Alert>

---
# Ordering

Source: https://hygraph.com/docs/api-reference/content-api/ordering

When fetching multiple entries you can use the `orderBy` argument to define the order of the returned records.

You can order results by all [System Fields](/docs/api-reference/schema/system-fields), and any non-relational custom field you define in your model, either ascending, or descending.

## Order by types

| Input Type         | Description                              |
| ------------------ | ---------------------------------------- |
| `[fieldName]_ASC`  | Order results by `fieldName` ascending.  |
| `[fieldName]_DESC` | Order results by `fieldName` descending. |

<Tabs panelHeight={200}>
  <TabsItem label="ASC">

```graphql
{
  posts(orderBy: createdAt_ASC) {
    id
    createdAt
  }
}
```

  </TabsItem>
  <TabsItem label="DESC">

```graphql
{
  posts(orderBy: createdAt_DESC) {
    id
    createdAt
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="warning">
You can only use **one** `inputType` with `orderBy` to order results.
</Alert>

## Nested ordering

You can use the `orderBy` with [two-way references](/docs/api-reference/schema/field-types#two-way-references). 

[One-way references](/docs/api-reference/schema/field-types#one-way-references) and [union-type relations](/docs/api-reference/schema/field-types#union) are not supported.

For example, let's imagine our post has a `authors` relation. The same `orderBy` rules apply.

```graphql
{
  posts {
    id
    createdAt
    relatedPosts(orderBy: createdAt_DESC) {
      id
      createdAt
    }
  }
}
```


---
# Pagination

Source: https://hygraph.com/docs/api-reference/content-api/pagination

## Paginate query results

Hygraph supports various arguments for paginating content entries:

| Argument | Type     | Definition                              |
| -------- | -------- | --------------------------------------- |
| `first`  | `Int`    | Seek forwards from start of result set. |
| `last`   | `Int`    | Seek backwards from end of result set.  |
| `skip`   | `Int`    | Skip result set by given amount.        |
| `before` | `String` | Seek backwards before specific ID.      |
| `after`  | `String` | Seeks forwards after specific ID.       |

<Tabs panelHeight={180}>
  <TabsItem label="first">

```graphql
{
  posts(first: 6) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="last">

```graphql
{
  posts(last: 6) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="skip">

```graphql
{
  posts(first: 6, skip: 6) {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="before">

```graphql
{
  posts(last: 6, before: "...") {
    id
  }
}
```

  </TabsItem>
  <TabsItem label="after">

```graphql
{
  posts(first: 6, after: "...") {
    id
  }
}
```

  </TabsItem>
</Tabs>

<Alert theme="warning">
You cannot combine `first` with `before`, or `last` with `after`.
</Alert>

<Alert theme="info">
The default result size of results returned by queries fetching multiple entries is `10`. You can provide a maximum of `100` to the `first`, or `last` arguments.

The limit of 10/100 applies to projects created after 14-06-2022. Projects created before that date have a limit of 100/1000.
</Alert>

## Pagination limits

To fetch the pagination limits of your projects, you need to access the [API Playground](/docs/api-reference/basics/api-playground) section of your Hygraph project, select `Management API` from the `Environment` dropdown located at the top of the screen, and run the following query:

```graphql
{
  viewer {
    project(id: "<PROJECTID>") {
      defaultPaginationSize
      maxPaginationSize
    }
  }
}
```

## Nested pagination

You can also use `first`, `last`, `skip`, `before`, and `after` arguments with any nested relations. For example, let's imagine our post has comments:

```graphql
{
  posts {
    id
    comments(first: 6, skip: 6) {
      id
      createdAt
    }
  }
}
```

## Relay cursor connections

Hygraph follows the Relay cursor connection specification. Each of your project models also contain a connection type, automatically managed by Hygraph.

The example below shows us how we can query for the first `3` posts, `after` the `cursor` (ID) `abc`. We can also query `pageInfo` to check whether there are more pages using `hasNextPage`.

The [`PageInfo`](/docs/api-reference/schema/system-fields#pageinfo) is useful when paginating.

```graphql
{
  postsConnection(first: 3, after: "abc") {
    edges {
      cursor
      node {
        id
        title
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
      pageSize
    }
  }
}
```

Learn more about [fetching with Relay](/docs/api-reference/content-api/queries#fetching-with-relay).


---
# Queries

Source: https://hygraph.com/docs/api-reference/content-api/queries

## Overview

Hygraph automatically generates queries for fetching single, and multiple entries for each defined content type belonging to your project.

You will need a [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens), or your [Public API Permissions](/docs/api-reference/basics/authorization#public-api-permissions) configured to query any data from your project.

## Auto-generated queries

When a new model is added to your project, there are two generated GraphQL queries added to your schema. The queries are named after the `API ID`, and `Plural API ID`.

<Alert theme="warning">
Both the single, and plural queries come with their own generated arguments for filtering, ordering, paginated, and getting content via their stage, revision, or locale.
</Alert>

For example, let's assume we have the model `Post` in our schema, and opted to keep the default generated API ID, and Plural API ID. The following queries would be generated by the API automatically:

- `post`
- `posts`
- `postVersion`
- `postsConnection`

## Fetching a single entry

The `post` query is what you would use to fetch one entry from the CMS.

You can fetch an individual entry by `id`, or any unique non-localized field defined in your content type.

```graphql
{
  post(where: { id: "..." }) {
    id
    title
  }
}
```

## Fetching multiple entries

The `posts` query is what you should use to fetch multiple entries from the CMS.

```graphql
{
  posts {
    id
  }
}
```

## Fetching relations

Imagine `posts` have a [one to many](/docs/api-reference/schema/field-types#one-to-many) relation with comments. With GraphQL you can query the related `comments` in the same request.

Here we will get all posts, and their comments.

```graphql
{
  posts {
    id
    comments {
      id
      author
    }
  }
}
```

Learn more about [Relations](/docs/api-reference/schema/field-types#reference).

## Fetching localizations

When fetching one or more entry, you can also fetch the localized entries. The default locale is set to `en`.

```graphql
{
  post(where: { id: "..." }, locales: [en, fr, de]) {
    title
  }

  posts(locales: [en, fr, de]) {
    title
  }
}
```

Learn more about [Localization](/docs/api-reference/content-api/localization).

### Locales inside components

When Localized fields only exist inside components, querying for content can be a bit misleading, especially when querying for locales. For instance, to query for the “Russian” Locale inside the components, specifying the locale in the query like the example below, will return null:

<Tabs panelHeight={420}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  pages(locales: ru) {
    id
    title
    slug
    pageElements {
      ... on Header {
        title
        contacts
      }
      ... on Footer {
        title
        texts
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "pages": []
  }
}
```

  </TabsItem>
</Tabs>

The reason for this is that the parent entry - Page - does not exist in the requested locale. Instead, asking for the "German" locale will return results like the one shown below, as this is the default - Base - locale, and entries will always exist in the default locale:

<Tabs panelHeight={420}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  pages(locales: de) {
    id
    title
    slug
    pageElements {
      ... on Header {
        title
        contacts
      }
      ... on Footer {
        title
        texts
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "pages": [
      {
        "id": "cl793mb8unoao0buuop235856",
        "title": "Pricing Page",
        "slug": "pricing",
        "pageElements": [
          {
            "title": "Subscription",
            "contacts": 430
          },
          {
            "title": "Contact",
            "texts": ["text 1", "text 2"]
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The Page model - parent entry in this example - has two fields, **Title** and **Slug**, that are not localized, as well as components. In turn, the components - children - have localized fields inside.
So, when you create an entry, only the components - children - have localization and not the parent entry. This means that, when you query for pages in a locale that is not the default and the parent entry does not exist in that locale, the query will return null.

There are three workarounds to query locales inside components:

- [Specify the locale for the component](/docs/api-reference/content-api/queries#specify-locale-for-the-component)
- [Use localizations inside the component in your query](/docs/api-reference/content-api/queries#use-localizations-inside-the-component-in-your-query)
- [Add a localized field to the parent entry](/docs/api-reference/content-api/queries#add-a-localized-field-to-the-parent-entry)

Here are some examples of these workarounds, following the German/Russian locales example we used before:

#### Specify locale for the component

To query for the Russian locale in our example, you simply need to specify the locale for the component, as shown below:

<Tabs panelHeight={340}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  pages {
    id
    title
    slug
    pageElements(locales: ru) {
      ... on Header {
        title
        contacts
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "pages": [
      {
        "id": "cl7g3mb8unoao0buuop235856",
        "title": "Pricing Page",
        "slug": "pricing",
        "pageElements": [
          {
            "title": "Подписка",
            "contacts": 320
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

#### Use localizations inside the component in your query

Another way to query for all the locales inside the component is to use **localizations** inside the component in your query, as follows:

<Tabs panelHeight={500}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  pages {
    id
    title
    slug
    pageElements {
      ... on Header {
        id
        localizations(includeCurrent: true, locales: [de, ru]) {
          title
          contacts
          locale
        }
      }
      ... on Footer {
        title
        texts
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "pages": [
      {
        "id": "cl7g3mb8unoao0buuop23586",
        "title": "Pricing Page",
        "slug": "pricing",
        "pageElements": [
          {
            "id": "cl7g3mb8unoap0buuwzpoipja",
            "localizations": [
              {
                "title": "Subscription",
                "contacts": 430,
                "locale": "de"
              },
              {
                "title": "Подписка",
                "contacts": 320,
                "locale": "ru"
              }
            ]
          },
          {
            "title": "Contact",
            "texts": ["text 1", "text 2"]
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

#### Add a localized field to the parent entry

The third and final workaround would be to add a localized field to the parent entry, as shown in the example below:

![Add a localized field to the parent entry](/images/docs/api-reference/content-api/locales-in-components-3rdworkaround-a.png)

This makes it possible to request the locale at the beginning of the query.

<Tabs panelHeight={500}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  pages(locales: ru) {
    id
    title
    slug
    pageElements {
      ... on Header {
        localizations(includeCurrent: true, locales: [de, ru]) {
          title
          contacts
          locale
        }
      }
      ... on Footer {
        title
        texts
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "pages": [
      {
        "id": "cl7g3mb8unoao0buuop23586",
        "title": "Pricing Page",
        "slug": "adding-russian-locale",
        "pageElements": [
          {
            "localizations": [
              {
                "title": "Subscription",
                "contacts": 430,
                "locale": "de"
              },
              {
                "title": "Подписка",
                "contacts": 320,
                "locale": "ru"
              }
            ]
          },
          {
            "title": "Contact",
            "texts": ["text 1", "text 2"]
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Fetching stages

When fetching entries, you can also specify the content `stage`.

The default content stage is set to `DRAFT`.

```graphql
{
  post(where: { id: "..." }, stage: PUBLISHED) {
    title
  }

  posts(stage: PUBLISHED) {
    title
  }
}
```

Learn more about [Content Stages](/docs/api-reference/content-api/content-stages).

## Fetching versions

You can fetch all data of a specific entry at a point in time using the automatically generated version query.

For example, using the `postVersion` query from above, we can make a request to get the specific revision through a query:

```graphql
{
  postVersion(where: { id: "abc123", revision: 1, stage: PUBLISHED }) {
    id
    revision
    data
  }
}
```

Learn more about [Versioning](/docs/api-reference/content-api/content-stages#versioning).

## Fetching workflow step

You can fetch the workflow step for an entry.

For example, for the model `Post` with workflow enabled, we can make a request to get the workflow step for an entry:

```graphql
{
  posts {
    id
    workflowStep
  }
}
```

Learn more about [Content workflows](/docs/developer-guides/project/content-workflows).

## Combining arguments

It is also possible to pass more than one query argument at a time.

For example, here we can get the first 3 posts, ordered by the created timestamp, where the title contains "Hygraph", and is published.

```graphql
{
  posts(
    where: { title_contains: "Hygraph" }
    orderBy: createdAt_DESC
    first: 3
    stage: PUBLISHED
  ) {
    id
  }
}
```

Learn more about these query arguments:

- [Filtering](/docs/api-reference/content-api/filtering)
- [Ordering](/docs/api-reference/content-api/ordering)
- [Pagination](/docs/api-reference/content-api/pagination)
- [Content Stage](/docs/api-reference/content-api/content-stages)

## Combining queries

Multiple queries can be executed in parallel via a single request to your endpoint.

For example, let's fetch our a single, and multiple posts in one request.

```graphql
{
  post(where: { id: "..." }) {
    id
    title
  }

  posts {
    id
    title
  }
}
```

For example, here we query for all events, and alias a second query with `previous` to better represent the applied filter.

```graphql
{
  events(where: { start_gt: "2020-10-07T09:00:00+00:00" }) {
    start
  }

  previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {
    start
  }
}
```

## Fetching with Relay

Hygraph also implements the Relay specification for querying records for all projects. You can fetch a single entry using the `node` query, or multiple entries with the `postsConnection` type.

When fetching a single entry with `node`, you will need to also pass the Edge Type inside the query.

### Node

```graphql
{
  node(id: "...") {
    ... on Post {
      id
      title
    }
  }
}
```

You can use the generated Relay connection query for querying multiple entries.

### Connection / Edges

```graphql
{
  postsConnection {
    edges {
      cursor
      node {
        id
        title
      }
    }
  }
}
```

Learn more about the [system fields](/docs/api-reference/schema/system-fields#connection-type-fields) for connection type queries.

## Directives

We support both the `@skip` and `@include` directives for use in your schema. This allows you to skip or include a field based on the value of the `if` argument you provide.

### @skip

For example, below can use the `@skip` directive to skip including a field based on the `skipTitle` variable value.

<Tabs panelHeight={180}>
  <TabsItem label="Query">

```graphql
query ($skipTitle: Boolean!) {
  posts {
    id
    title @skip(if: $skipTitle)
  }
}
```

  </TabsItem>
  <TabsItem label="Variables">

```json
{
  "skipTitle": true
}
```

  </TabsItem>
</Tabs>

### @include

For example, below can use the `@include` directive to include a field (including relations) based on the `includeAuthor` variable value.

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query ($includeAuthor: Boolean!) {
  posts {
    id
    title
    author @include(if: $includeAuthor) {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Variables">

```json
{
  "includeAuthor": true
}
```

  </TabsItem>
</Tabs>

## Variables

It's recommended you use GraphQL variables when working with queries that use any variable data values. This is useful for reusing queries across your application.

For example, to fetch a post by slug, you'd first need to define the query name, and the arguments with the type, and pass that along to the query itself.

```graphql
query GetPostBySlug($slug: String!) {
  post(where: { slug: $slug }) {
    id
    title
  }
}
```

When working with a GraphQL client, this is how you'd typically work with variables:

<Tabs panelHeight={450}>
  <TabsItem label="GraphQL Request">

```js
import { request, gql } from 'graphql-request';

const endpoint = 'YOUR_HYGRAPH_ENDPOINT';

const query = gql`
  query GetPostBySlug($slug: String!) {
    post(where: { slug: $slug }) {
      id
      title
    }
  }
`;

const variables = {
  slug: 'hygraph-is-awesome',
};

const data = await request(endpoint, query, variables);
```

  </TabsItem>
  <TabsItem label="Apollo Client (React)">

```js
import { gql, useQuery } from '@apollo/client';

const query = gql`
  query GetPostBySlug($slug: String!) {
    post(where: { slug: $slug }) {
      id
      title
    }
  }
`;

function PostPage({ breed }) {
  const { loading, error, data } = useQuery(query, {
    variables: { slug: 'hygraph-is-awesome' },
  });

  if (loading) return null;
  if (error) return `Error! ${error}`;

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
```

  </TabsItem>
</Tabs>


---
# Rich Text field

Source: https://hygraph.com/docs/api-reference/content-api/rich-text-field

## Overview

The `RichText` field type is an advanced String field that returns your content in 4 different formats by default: `raw`, `HTML`, `markdown`, and `text`. `JSON` is also available when embeds are enabled.

The Rich Text field renders an advanced `textarea` with tools to add headings, links, tables, images, lists, etc.

When a Rich Text field is added to your model, it will automatically generate the following types:

```graphql
type RichText {
  raw: RichTextAST!
  html: String!
  markdown: String!
  text: String!
  json: RichTextAST!
}
```

## Rich Text data

Let's talk about Rich Text data in more detail.

- **Raw:** `raw` AST (Slate Nodes) offers complete control over how nodes are presented to the user.
- **JSON:** `JSON` representations of RTE allows as much control as `raw` does, but offers the possibility of creating embeds.

  <Alert theme="info">
  `RichText` will include the field `JSON` in addition to `raw` only if Rich Text Embeds are enabled. Both `JSON` and `raw` are aliases, but if you have embeds enabled you should ideally use `JSON`.
  </Alert>

- **HTML:** `HTML` can be used with a Rich Text renderer for customization purposes. While rendering the HTML of your rich text is simple, it doesn't offer great customization.
- **Markdown:** `Markdown` - like `HTML` - can be used for customization. While `markdown` is easier to read and write - specially for users without a technical background - it's not as expressive as `HTML`. To present `markdown` on a page, you'll need a `markdown` parser that will convert `markdown` to `HTML`.
- **Text:** `text` is mostly used for excerpts, as links, images, and even line breaks are removed.

### Use Cases

- **Raw:** Use `raw` when you want to control the rendered output using our render libraries.
- **JSON:** Use `JSON` for the same as `raw` but when you also need embeds.
- **HTML / Markdown:** Use these when you need to make customizations and want to insert pre-built `HTML` or `markdown` into an app.
- **Text:** Use `text` when you want to provide the text as data to a script, such as making full-text search.

### Examples

This section takes a simple Rich Text piece with a title, a paragraph, a link, and bold text, and offers its `JSON`, `HTML`, `Markdown`, and `Text` representations.

<Tabs panelHeight={900}>
  <TabsItem label="JSON">

```
"json": {
          "children": [
            {
              "type": "heading-one",
              "children": [
                {
                  "text": "Example Rich Text Copy"
                }
              ]
            },
            {
              "type": "paragraph",
              "children": [
                {
                  "text": "This is a regular paragraph, including a "
                },
                {
                  "href": "https://hygraph.com/docs",
                  "type": "link",
                  "children": [
                    {
                      "text": "hyperlink"
                    }
                  ]
                },
                {
                  "text": " and "
                },
                {
                  "bold": true,
                  "text": "bold text"
                },
                {
                  "text": "."
                }
              ]
            }
          ]
        }
```

  </TabsItem>
  <TabsItem label="HTML">

```
"html": "<h1>Example Rich Text Copy</h1><p>This is a regular paragraph, including a <a title=\"https://hygraph.com/docs\" href=\"https://hygraph.com/docs\">hyperlink</a> and <strong>bold text</strong>.</p>"
```

  </TabsItem>
  <TabsItem label="Markdown">

```markdown
"markdown": "# Example Rich Text Copy\n\nThis is a regular paragraph, including a [hyperlink](https://hygraph.com/docs \"https://hygraph.com/docs\") and **bold text**.\n"
```

  </TabsItem>
  <TabsItem label="Text">

```text
"text": "Example Rich Text Copy\\nThis is a regular paragraph, including a \\nhyperlink\\n and \\nbold text\\n."
```

  </TabsItem>
</Tabs>

## Rich Text embeds

<Alert theme="info">
If Rich Text Embeds are enabled, `RichText` will include the field `JSON` in addition to `raw`.
</Alert>

For example, we can query all of those on our `RichText` field type `content`:

<Tabs panelHeight={250}>
  <TabsItem label="Request">

```graphql
{
  posts {
    content {
      raw
      html
      markdown
      text
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "posts": [
      {
        "content": {
          "raw": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": "GraphQL CMS"
                  }
                ]
              }
            ]
          },
          "html": "<p>GraphQL CMS</p>",
          "markdown": "GraphQL CMS\n",
          "text": "GraphQL CMS"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### Embed assets

You can also embed [Assets](/docs/api-reference/assets/embedded-types) and other models inside Rich Text as **block, inline or link embeds**.

![Rich Text Asset Embeds UI](/images/docs/api-reference/schema/rich-text-embeds.png)

<Alert theme="info">
You can find out how to enable Rich Text embeds in our [field configuration](/docs/api-reference/schema/field-configuration#rich-text-fields-only-embed-options) docs.
</Alert>

### Rich Text embeds & API types

With Rich Text Embeds enabled, your API will have some new types added. The name of your field will be now a type appended by `RichText`, and `RichTextEmbeddedTypes` inside your schema.

For example, if you had the model `Post` and field `content`, the types generates would be `PostContentRichText`, and `PostContentRichTextEmbeddedTypes` respectively.

The `PostContentRichText` type will look like the following:

```graphql
type RichText {
  json: RichTextAST!
  html: String!
  markdown: String!
  text: String!
  references: [PostContentRichTextEmbeddedTypes!]!
}
```

The `references` field will be a union relation to the types you embedded, for example `Asset`.

You should use the `references` field when querying `JSON` to get the `URL` (with any [transformations](/docs/api-reference/assets/transformations), `handle`, or any of the [Asset fields](/docs/api-reference/schema/system-fields#asset-fields).

<Tabs panelHeight={420}>
  <TabsItem label="Query">

```graphql
{
  posts {
    content {
      json
      html
      markdown
      text
      references {
        __typename
        ... on Asset {
          url
          handle
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "posts": [
      {
        "content": {
          "json": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": "Hygraph Rich Text Embeds"
                  }
                ]
              },
              {
                "type": "embed",
                "nodeId": "cko2lq2u0031r0844xnvurz05",
                "children": [
                  {
                    "text": ""
                  }
                ],
                "nodeType": "Asset"
              },
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": ""
                  }
                ]
              }
            ]
          },
          "html": "<p>Hygraph Rich Text Embeds</p><div data-gcms-embed-type=\"Asset\" data-gcms-embed-id=\"cko2lq2u0031r0844xnvurz05\"></div><p></p>",
          "markdown": "Hygraph Rich Text Embeds\n\n\n",
          "text": "Hygraph Rich Text Embeds\\n\\n",
          "references": [
            {
              "__typename": "Asset",
              "url": "https://media.graphassets.com/xSIoGkATQybd8S2SgA5Q",
              "handle": "xSIoGkATQybd8S2SgA5Q"
            }
          ]
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

The `HTML` response will return `gcms-embed-type` and `gcms-embed-id` data attributes for the embedded types. A block embed is returned as `div` and an inline embed as `span` with a `data-gcms-embed-inline` attribute. A link embed is returned as an `a`-tag with a `data-gcms-embed-id` and `data-gcms-embed-type` attribute.

<Tabs panelHeight={130}>
  <TabsItem label="Block">
    ```html
    <div
      data-gcms-embed-type="Asset"
      data-gcms-embed-id="cko2lq2u0031r0844xnvurz05"
    ></div>
    ```
  </TabsItem>
  <TabsItem label="Inline">
    ```html
    <span
      data-gcms-embed-type="Author"
      data-gcms-embed-id="ckwyytv5k003s0791zitq6alu"
      data-gcms-embed-inline
    ></span>
    ```
  </TabsItem>
  <TabsItem label="Link">
    ```html
    <a
      data-gcms-embed-id="cl0sa2kc50sb80axsu0kcaeaa"
      data-gcms-embed-type="Post"
    >
      link text
    </a>
    ```
  </TabsItem>
</Tabs>

Hygraph uses <Link href="https://docs.slatejs.org" target="_blank">Slate 0.5</Link> for `RichTextAST`.

<Alert theme="info">
If you are programmatically creating content entries with Rich Text, you should use the <Link href="https://github.com/hygraph/rich-text/tree/main/packages/html-to-slate-ast" target="_blank"><code>@graphcms/html-to-slate-ast</code></Link> package.
</Alert>

## Mutations for Rich Text fields

When creating or updating entries, ensure your mutation payload matches the schema type shown in the API Playground. For localized models or fields, you must include a locale property. Incorrectly structured payloads are a common cause of <code>Invalid payload / could not transform RichText</code> errors.

<Alert theme="info">
Even if the field allows embeds, the structure remains the same. Always send an object containing a `children` array.
</Alert>

### Create rich text fields

Provide the AST object directly. Do not wrap it in a property such as `raw` or `json`.

<Tabs panelHeight={380}>
  <TabsItem label="Create rich text field">
    ```graphql
    mutation {
      createPost(
        data: {
          content: {
            children: [{type: "paragraph", children: [{text: "This is old."}]}]
          }
        }
      ) {
        id
        content {
          json
          html
        }
      }
    }
    ```
  </TabsItem>
  <TabsItem label="Result - Create rich text field">
    ```json
    {
      "data": {
        "createPost": {
          "id": "cmgqebp1hxdqm07w0fgaj7u7g",
          "content": {
            "json": {
              "children": [
                {
                  "type": "paragraph",
                  "children": [
                    {
                      "text": "This is old."
                    }
                  ]
                }
              ]
            },
            "html": "<p>This is old.</p>"
          }
        }
      }
    }
    ```
     </TabsItem>
</Tabs>

### Update rich text fields

Provide the AST object directly. Do not wrap it in a property such as `raw` or `json`.

<Tabs panelHeight={380}>
  <TabsItem label="Update rich text field">
    ```graphql
    mutation {
      updatePost(
        where: {id: "cmgqe9mbzxqx607uu4uzrde44"}
        data: {
          content: {
            children: [{ type: "paragraph", children: [{ text: "This is new." }] }]
          }
        }
      ) {
        id
        content {
          json
        }
      }
    }
    ```
  </TabsItem>
  <TabsItem label="Result - Update rich text field">
    ```json
    {
      "data": {
        "updatePost": {
          "id": "cmgqe9mbzxqx607uu4uzrde44",
          "content": {
            "json": {
              "children": [
                {
                  "type": "paragraph",
                  "children": [
                    {
                      "text": "This is new."
                    }
                  ]
                }
              ]
            }
          }
        }
      }
    }
    ```
     </TabsItem>
</Tabs>

### Create rich text fields with locale

Provide the AST object directly. Do not wrap it in a property such as `raw` or `json`.

<Tabs panelHeight={660}>
  <TabsItem label="Create rich text field with locale">
    ```graphql
    mutation {
      createPost(
        data: {
          localizations: {
            create: [
              {
                locale: de
                data: {
                  content: {
                    children: [
                      { type: "paragraph", children: [{ text: "Das ist alt." }] }
                    ]
                  }
                }
              }
            ]
          }
        }
      ) {
        id
        localizations(locales: [de]) {
          locale
          content {
            raw
          }
        }
      }
    }
    ```
  </TabsItem>
  <TabsItem label="Result - Create rich text field with locale">
    ```json
    {
      "data": {
        "createPost": {
          "id": "cmgqem7eoym1d07uu2ezhlj5t",
          "localizations": [
            {
              "locale": "de",
              "content": {
                "raw": {
                  "children": [
                    {
                      "type": "paragraph",
                      "children": [
                        {
                          "text": "Das ist alt."
                        }
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
    ```
     </TabsItem>
</Tabs>

### Update rich text fields with locale

Provide the AST object directly. Do not wrap it in a property such as `raw` or `json`.

<Tabs panelHeight={680}>
  <TabsItem label="Update rich text field with locale">
    ```graphql
    mutation {
      updatePost(
        where: { id: "cmgqem7eoym1d07uu2ezhlj5t" }
        data: {
          localizations: {
            update: [
              {
                locale: de
                data: {
                  content: {
                    children: [
                      { type: "paragraph", children: [{ text: "Das ist neu." }] }
                    ]
                  }
                }
              }
            ]
          }
        }
      ) {
        id
        localizations(locales: [de]) {
          locale
          content {
            raw
          }
        }
      }
    }
    ```
  </TabsItem>
  <TabsItem label="Result - Update rich text field with locale">
    ```json
    {
      "data": {
        "updatePost": {
          "id": "cmgqem7eoym1d07uu2ezhlj5t",
          "localizations": [
            {
              "locale": "de",
              "content": {
                "raw": {
                  "children": [
                    {
                      "type": "paragraph",
                      "children": [
                        {
                          "text": "Das ist neu."
                        }
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
    ```
     </TabsItem>
</Tabs>

## Use JSON representation of RTE for customization

You can work with the **Rich Text field** to take the data that the editors put in Hygraph, and manipulate it for display in the front end.

The following example shows data available on a blog post, with the Rich Text content in `HTML` and `markdown`:

<Tabs panelHeight={280}>
 <TabsItem label="Query">

```graphql
query MyQuery($id: ID, $slug: String) {
  values: post(where: { id: $id, slug: $slug }) {
    title
    slug
    id
    content {
      html
      markdown
    }
  }
}
```

 </TabsItem>
 <TabsItem label="Variables">

```json
{
  "id": "clbdn2fjithnl0amxwm8wtell"
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "values": {
      "title": "Test",
      "slug": "test",
      "id": "clbdn2fjithnl0amxwm8wtell",
      "content": {
        "html": "<h1>Lorem Ipsum</h1><h4>&quot;Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...&quot;</h4><h5>&quot;There is no one who loves pain itself, who seeks after it and wants to have it, simply because it is pain...&quot;</h5><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc interdum mauris libero. Aliquam in iaculis nibh. Duis sagittis, orci sit amet hendrerit pellentesque, velit felis lobortis purus, vitae finibus libero risus quis ipsum. Curabitur in malesuada odio. Quisque quis metus quis augue lacinia euismod vel quis orci. Fusce condimentum ultricies mollis. Morbi et ultricies augue. Integer massa libero, elementum nec ante at, blandit auctor risus. Nulla et dignissim turpis. Vivamus pharetra turpis eu sem maximus egestas. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. In a pulvinar dui. Etiam varius justo quis purus hendrerit, sed tristique ex pulvinar. Integer vel lobortis magna. Suspendisse potenti. Morbi faucibus sem eget enim posuere, vitae vestibulum felis sodales.</p><p>Fusce suscipit sed dolor eu convallis. Nulla et velit ut lacus ullamcorper varius vel sit amet justo. Nullam condimentum dolor a ligula placerat, vitae sagittis elit efficitur. Donec ac elit fermentum, vehicula dui eget, condimentum ante. Aenean in nisl faucibus neque feugiat suscipit. Aenean sit amet facilisis ante, sed semper ipsum. Proin id nulla odio. Maecenas condimentum placerat laoreet. Aliquam at sodales tortor. Nam tortor dui, maximus nec imperdiet ut, bibendum vel felis. Duis hendrerit vulputate finibus. In hac habitasse platea dictumst. Pellentesque sed posuere ex. Nullam metus erat, finibus nec ultricies nec, egestas sed ipsum.</p><p>Nulla varius mauris sed justo egestas, eu dictum urna dictum. Aenean varius dui convallis vehicula suscipit. In hac habitasse platea dictumst. Nullam euismod vel dui ac blandit. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Sed vitae lorem lacinia, mollis risus volutpat, malesuada risus. Maecenas lacinia sem in odio vestibulum, at dictum metus finibus. Morbi turpis tellus, egestas eu molestie nec, sagittis ac enim. Morbi facilisis finibus odio, eget consequat ipsum porttitor non. Nunc risus ipsum, congue blandit lacus eu, lacinia hendrerit nulla. Donec congue suscipit velit, a aliquet dolor venenatis nec. In eget ullamcorper massa. Ut efficitur felis vel rhoncus sollicitudin.</p>",
        "markdown": "# Lorem Ipsum\n\n#### \"Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...\"\n\n##### \"There is no one who loves pain itself, who seeks after it and wants to have it, simply because it is pain...\"\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc interdum mauris libero. Aliquam in iaculis nibh. Duis sagittis, orci sit amet hendrerit pellentesque, velit felis lobortis purus, vitae finibus libero risus quis ipsum. Curabitur in malesuada odio. Quisque quis metus quis augue lacinia euismod vel quis orci. Fusce condimentum ultricies mollis. Morbi et ultricies augue. Integer massa libero, elementum nec ante at, blandit auctor risus. Nulla et dignissim turpis. Vivamus pharetra turpis eu sem maximus egestas. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. In a pulvinar dui. Etiam varius justo quis purus hendrerit, sed tristique ex pulvinar. Integer vel lobortis magna. Suspendisse potenti. Morbi faucibus sem eget enim posuere, vitae vestibulum felis sodales.\n\nFusce suscipit sed dolor eu convallis. Nulla et velit ut lacus ullamcorper varius vel sit amet justo. Nullam condimentum dolor a ligula placerat, vitae sagittis elit efficitur. Donec ac elit fermentum, vehicula dui eget, condimentum ante. Aenean in nisl faucibus neque feugiat suscipit. Aenean sit amet facilisis ante, sed semper ipsum. Proin id nulla odio. Maecenas condimentum placerat laoreet. Aliquam at sodales tortor. Nam tortor dui, maximus nec imperdiet ut, bibendum vel felis. Duis hendrerit vulputate finibus. In hac habitasse platea dictumst. Pellentesque sed posuere ex. Nullam metus erat, finibus nec ultricies nec, egestas sed ipsum.\n\nNulla varius mauris sed justo egestas, eu dictum urna dictum. Aenean varius dui convallis vehicula suscipit. In hac habitasse platea dictumst. Nullam euismod vel dui ac blandit. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Sed vitae lorem lacinia, mollis risus volutpat, malesuada risus. Maecenas lacinia sem in odio vestibulum, at dictum metus finibus. Morbi turpis tellus, egestas eu molestie nec, sagittis ac enim. Morbi facilisis finibus odio, eget consequat ipsum porttitor non. Nunc risus ipsum, congue blandit lacus eu, lacinia hendrerit nulla. Donec congue suscipit velit, a aliquet dolor venenatis nec. In eget ullamcorper massa. Ut efficitur felis vel rhoncus sollicitudin.\n"
      }
    }
  }
}
```

 </TabsItem>
</Tabs>

Hygraph automatically serializes the content into `HTML` and/or `markdown` that the front end can simply display. **This does not allow customization**.

Instead of these two things, you can get the JSON representation, which will display as `JSON AST` in a tree with nested levels.

<Tabs panelHeight={250}>
 <TabsItem label="Query">

```graphql
query MyQuery($id: ID, $slug: String) {
  values: post(where: { id: $id, slug: $slug }) {
    title
    slug
    id
    content {
      json
    }
  }
}
```

 </TabsItem>
 <TabsItem label="Variables">

```json
{
  "id": "clbdn2fjithnl0amxwm8wtell"
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "values": {
      "title": "Test",
      "slug": "test",
      "id": "clbdn2fjithnl0amxwm8wtell",
      "content": {
        "json": {
          "children": [
            {
              "type": "heading-one",
              "children": [
                {
                  "text": "Lorem Ipsum"
                }
              ]
            },
            {
              "type": "heading-four",
              "children": [
                {
                  "text": "\"Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...\""
                }
              ]
            },
            {
              "type": "heading-five",
              "children": [
                {
                  "text": "\"There is no one who loves pain itself, who seeks after it and wants to have it, simply because it is pain...\""
                }
              ]
            },
            {
              "type": "paragraph",
              "children": [
                {
                  "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc interdum mauris libero. Aliquam in iaculis nibh. Duis sagittis, orci sit amet hendrerit pellentesque, velit felis lobortis purus, vitae finibus libero risus quis ipsum. Curabitur in malesuada odio. Quisque quis metus quis augue lacinia euismod vel quis orci. Fusce condimentum ultricies mollis. Morbi et ultricies augue. Integer massa libero, elementum nec ante at, blandit auctor risus. Nulla et dignissim turpis. Vivamus pharetra turpis eu sem maximus egestas. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. In a pulvinar dui. Etiam varius justo quis purus hendrerit, sed tristique ex pulvinar. Integer vel lobortis magna. Suspendisse potenti. Morbi faucibus sem eget enim posuere, vitae vestibulum felis sodales."
                }
              ]
            },
            {
              "type": "paragraph",
              "children": [
                {
                  "text": "Fusce suscipit sed dolor eu convallis. Nulla et velit ut lacus ullamcorper varius vel sit amet justo. Nullam condimentum dolor a ligula placerat, vitae sagittis elit efficitur. Donec ac elit fermentum, vehicula dui eget, condimentum ante. Aenean in nisl faucibus neque feugiat suscipit. Aenean sit amet facilisis ante, sed semper ipsum. Proin id nulla odio. Maecenas condimentum placerat laoreet. Aliquam at sodales tortor. Nam tortor dui, maximus nec imperdiet ut, bibendum vel felis. Duis hendrerit vulputate finibus. In hac habitasse platea dictumst. Pellentesque sed posuere ex. Nullam metus erat, finibus nec ultricies nec, egestas sed ipsum."
                }
              ]
            },
            {
              "type": "paragraph",
              "children": [
                {
                  "text": "Nulla varius mauris sed justo egestas, eu dictum urna dictum. Aenean varius dui convallis vehicula suscipit. In hac habitasse platea dictumst. Nullam euismod vel dui ac blandit. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Sed vitae lorem lacinia, mollis risus volutpat, malesuada risus. Maecenas lacinia sem in odio vestibulum, at dictum metus finibus. Morbi turpis tellus, egestas eu molestie nec, sagittis ac enim. Morbi facilisis finibus odio, eget consequat ipsum porttitor non. Nunc risus ipsum, congue blandit lacus eu, lacinia hendrerit nulla. Donec congue suscipit velit, a aliquet dolor venenatis nec. In eget ullamcorper massa. Ut efficitur felis vel rhoncus sollicitudin."
                }
              ]
            }
          ]
        }
      }
    }
  }
}
```

 </TabsItem>
</Tabs>

<Alert theme="warning">
Remember that `Richtext` will only include the field `JSON` if Rich Text embeds are enabled for the model you're using.
</Alert>

As you can see in the `results` tab of the above query, this breaks up the initial data into a `JSON` representation that a renderer can understand.

This allows you to take that data and manipulate it in order to override any default renderer or add renderers for custom elements, creating a custom display logic for your front end.

You will do this by creating an `HTML` element containing the manipulated data, which will then be rendered via the `astToHtmlString` method that's available on our <Link href="https://github.com/hygraph/rich-text/tree/main/packages/html-renderer" target="_blank">Rich Text HTML renderer</Link>. We also have a <Link href="https://hygraph.com/blog/hygraph-react-rich-text-renderer" target="_blank">React version</Link> of this.

<Alert theme="info">
Click <Link href="https://hygraph.com/blog/styling-rich-text-tailwindcss" target="_blank">here</Link> to access a detailed example on <b>how to style Rich Text using TailwindCSS</b>.
</Alert>

By styling your Rich Text fields, you can either customize how your Rich Text will display throughout your website, or even have multiple types of Rich Text fields that do different things.

## Resources

- [Hygraph's Rich Text editor:](/docs/developer-guides/content/rich-text-editor) Hygraph's UI Rich Text field feature walkthrough.
- <Link href="https://hygraph.com/blog/styling-rich-text-tailwindcss" target="_blank">Styling Rich Text with TailwindCSS:</Link> Detailed tutorial on how to use the `JSON` representation from the RTE to create custom elements for each text-based element of Rich Text.
- <Link href="https://hygraph.com/blog/hygraph-react-rich-text-renderer" target="_blank">Introducing the Hygraph React Rich Text Renderer:</Link> Blog post on how to render Hygraph documents using Rich Text in your application easily using our available packages.
- [Rich Text editor UI guide:](/docs/developer-guides/content/rich-text-editor) Guide on how to use Hygraph's Rich Text editor in the content editor of your project.


---
# Variables

Source: https://hygraph.com/docs/api-reference/content-api/variables

## Overview

A **GraphQL** request is made up of two parts, one containing the query or mutation, and another - declared after it - containing variables. Variables can be used to create dynamic queries and mutations, as they allow you to pass dynamic values as a separate dictionary.

In other words, variables in GraphQL are passed like arguments to a function allowing said arguments to be extracted as variables from queries and mutations, simplifying them.

## Variable definitions

Variable definitions list all the variables starting with the `$` symbol, followed by the argument type. They can be optional or required. Required variable definitions carry an `!` next to the type.

So, `($slug: String!)` defines a variable with name slug, of type String, that is required.

<Alert theme="info">
If the field you're passing the variable into requires a non-null argument, you need to make the variable required as well.
</Alert>

If you want to define more than one variable, you need to write one next to the other in the query. You can separate them with a comma, but it's not necessary. Here's an example that fetches posts that have either the `title` or `slug` provided in the query variables:

<Tabs panelHeight={200}>
 <TabsItem label="Query">

```graphql
query name($title: String, $slug: String) {
  posts(where: { OR: [{ title: $title }, { slug: $slug }] }) {
    id
    title
    slug
  }
}
```

 </TabsItem>
 <TabsItem label="Variables">

```json
{
  "title": "test",
  "slug": "test"
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "posts": [
      {
        "id": "clbdn2fjithnl0amxwm8wtell",
        "title": "Test",
        "slug": "test"
      }
    ]
  }
}
```

 </TabsItem>
</Tabs>

### Define a default

When you define a variable, you can also define the default that it will fall back to when you're not passing a value.

To assign a default value to a variable in the query, add it after the type declaration, as follows:

<Tabs panelHeight={180}>
 <TabsItem label="Query">

```graphql
query GetPostBySlug($slug: String = "test") {
  post(where: { slug: $slug }) {
    id
    title
  }
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "post": {
      "id": "clbdn2fjithnl0amxwm8wtell",
      "title": "Test"
    }
  }
}
```

 </TabsItem>
</Tabs>

In the above example, we set the string `test` as the default for `$slug`. So, if we're not passing any variable values, it uses its default and returns posts where the `slug` is `test`.

## Input types

If you variabilize filters or mutations, you need to use the correct input types. The auto generated documentation in our API Playground contains this information:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/vzHHRGxvR264jQ5YN5pv" caption="Using variables in the API playground" />

<Alert theme="info" title="Pro Tip">
Hover over your query parameters and:

- <b>CMD + Click</b> on Mac.

- <b>Control + Click</b> on Windows.

This opens the documentation explorer, allowing you to look through the API and find the correct input type you need to use. The documentation explorer will also show you the parameters you can pass in your query.
</Alert>

## Queries

The following example query fetches a post by slug. In order to do this we have defined the query name and the arguments with the type, and passed that along to the query itself.

<Tabs panelHeight={180}>
 <TabsItem label="Query">

```graphql
query GetPostBySlug($slug: String!) {
  post(where: { slug: $slug }) {
    id
    title
  }
}
```

 </TabsItem>
 <TabsItem label="Variables">

```json
{
  "slug": "title-slug"
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "post": {
      "id": "clb5blvzekcnh0altbyxx220a",
      "title": "Title slug"
    }
  }
}
```

 </TabsItem>
</Tabs>

## Filters

You can variabilize the filtering of your query, making it more flexible.

The following query contains dynamic filters with values you can define with the variables you pass:

<Tabs panelHeight={190}>
 <TabsItem label="Query">

```graphql
query name($where: PostWhereInput) {
  posts(where: $where) {
    id
    title
    slug
  }
}
```

 </TabsItem>
 <TabsItem label="Variables">

```json
{
  "where": { "slug": "test" }
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "posts": [
      {
        "id": "clbdn2fjithnl0amxwm8wtell",
        "title": "Test",
        "slug": "test"
      }
    ]
  }
}
```

 </TabsItem>
</Tabs>

This way your query can stay the same and instead of creating a new query from scratch every time, you can simply change the values passed with the variables.

## Mutations

Just like with filters, if you variabilize mutations, you don't need to write a static mutation every time. Instead, you will keep the same query and only alter the variables.

<Tabs panelHeight={180}>
 <TabsItem label="Mutation">

```graphql
mutation name($data: PostCreateInput!) {
  createPost(data: $data) {
    id
  }
}
```

 </TabsItem>
 <TabsItem label="Variables">

```json
{
  "data": { "title": "post", "slug": "post" }
}
```

 </TabsItem>
 <TabsItem label="Result">

```json
{
  "data": {
    "createPost": {
      "id": "clbdo25sbtqei0bn1tuovkf8t"
    }
  }
}
```

 </TabsItem>
</Tabs>


---
# API Reference

Source: https://hygraph.com/docs/api-reference/index

Our API reference contains information on how to work with our Content API, as well as our Schema, Management SDK, and other developer tools.

This section of our documentation covers:

## Basics

| Document                                                    | Contents                                                                                                                                                                                            |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Authorization](/docs/api-reference/basics/authorization)   | Contains information about Public API permissions, Permanent auth tokens, and API endpoints                                                                                                         |
| [Permissions](/docs/api-reference/basics/permissions)       | Contains information about our advanced permissions feature, which allows you to configure granular permissions to access content from a Hygraph project.                                           |
| [Caching](/docs/api-reference/basics/caching)               | Contains information about cache management through two different content API endpoints: the regular read & write endpoint, and the high performance read-only endpoint.                            |
| [Environments](/docs/api-reference/basics/environments)     | Contains information about working with different environments.                                                                                                                                     |
| [Errors](/docs/api-reference/basics/errors)                 | Contains information about common error codes.                                                                                                                                                      |
| [Webhooks](/docs/api-reference/basics/webhooks)             | Contains information about working with webhooks in your Hygraph project.                                                                                                                           |
| [API Playground](/docs/api-reference/basics/api-playground) | Contains information about Hygraph's API Playground, which is a great way to experiment with querying, and mutating data.                                                                           |
| [Rate limits](/docs/api-reference/basics/api-limits)       | Contains information about the limits to the number of uncached requests you can make to your content API. Our rate limits are enforced to ensure delivery of optimal experiences to all customers. |

## Schema

| Document                                                              | Contents                                                                                                                                                                                  |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Models](/docs/api-reference/schema/models)                           | Contains information about working with models. The models you create and the fields you add define your project's schema.                                                                |
| [System fields](/docs/api-reference/schema/system-fields)             | Contains information about system fields. All default and custom content types come with some managed system fields.                                                                      |
| [Field types](/docs/api-reference/schema/field-types)                 | Contains information about the field types you can use in your project. It also contains information about how input types work for filtering, ordering, paginating, and mutating data.   |
| [Field configuration](/docs/api-reference/schema/field-configuration) | Contains information on how to configure field types for your model with validations, visibility options, and more.                                                                       |
| [Enumerations](/docs/api-reference/schema/enumerations)               | Contains information on how to work with enumerations.                                                                                                                                    |
| [Taxonomies](/docs/api-reference/schema/taxonomies)               | Contains information on how to work with taxonomies.
| [Components](/docs/developer-guides/schema/components)                | Contains information on how to work with components. A component is a predefined set of fields that can be reused across models and content entries.                                      |
| [Reserved terms](/docs/developer-guides/schema/reserved-terms)        | This document contains a list of reserved terms, organized by category. Attempting to use these terms will result in a warning, informing you that you must use a different word instead. |
| [Environment diffing](/docs/api-reference/schema/environment-diffing) | Contains information on how to use environment diffing to compare two schemas, then apply those changes using the **Management API**.                                                     |
| [Schema as code](/docs/api-reference/schema/schema-as-code)           | Contains information on how to export your schema in the form of code. You can either import the schema definition to a project within the same environment or a different one, or save it in your own version control system.                                                                                                                    |

## Content API

| Document                                                         | Contents                                                                                                                                                                                                          |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Queries](/docs/api-reference/content-api/queries)               | Contains information about working with queries. Hygraph automatically generates queries for fetching single and multiple entries for each defined content type belonging to your project.                        |
| [Mutations](/docs/api-reference/content-api/mutations)           | Contains information about working with mutations. Your project endpoint exposes GraphQL mutations you can use to modify the contents of your project.                                                            |
| [Filtering](/docs/api-reference/content-api/filtering)           | Contains information about using filters. Hygraph automatically creates filters for types you add to your content models. These filters can be applied to a single or multiple entries, and nested object fields. |
| [Ordering](/docs/api-reference/content-api/ordering)             | Contains information about ordering. When fetching multiple entries you can use the `orderBy` argument to define the order of the returned records.                                                               |
| [Pagination](/docs/api-reference/content-api/pagination)         | Contains information about pagination. Hygraph supports various arguments for paginating content entries.                                                                                                         |
| [Content stages](/docs/api-reference/content-api/content-stages) | Contains information about content stages. You can create your own content stages inside the Hygraph UI, and query content from these stages, as well as publish to.                                              |
| [Localization](/docs/api-reference/content-api/localization)     | Contains information about localization. Hygraph boasts a flexible localization API that you can use to publish content for all or specific locales in your project.                                              |
| [Variables](/docs/api-reference/content-api/variables)           | Contains information about working with variables, and how to use them to create dynamic queries and mutations.                                                                                                   |
| [Rich text](/docs/api-reference/content-api/rich-text-field)     | Contains information on Hygraph's rich text field and how to use it to customize your front end.                                                                                                                  |
| [Headers](/docs/api-reference/content-api/headers)               | Contains information on use headers as a global way to send more specific requests to our API.                                                                                                                    |

## Assets

| Document                                                            | Contents                                                                                                                                                                        |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Overview](/docs/api-reference/assets/assets-overview)              | Overview to our asset upload API reference.                                                                                                                                     |
| [Fetching assets](/docs/api-reference/assets/fetching-assets)       | Contains information about fetching assets using our Content API.                                                                                                               |
| [Referencing assets](/docs/api-reference/assets/referencing-assets) | Contains information about referencing assets using our asset upload API.                                                                                                       |
| [Transformations](/docs/api-reference/assets/transformations)       | Contains information about passing transformations using our asset upload API: resize images, convert file type, validating transforms, combining transforms, alias transforms. |
| [Uploading assets](/docs/api-reference/assets/uploading-assets)     | Contains information about uploading assets using our asset upload API.                                                                                                         |
| [Updating assets](/docs/api-reference/assets/updating-assets)       | Contains information about updating assets using our asset upload API.                                                                                                          |
| [Deleting assets](/docs/api-reference/assets/deleting-assets)       | Contains information about deleting assets using our asset upload API.                                                                                                          |
| [Publishing assets](/docs/api-reference/assets/publishing-assets)   | Contains information about publishing assets using our asset upload API.                                                                                                        |
| [Localized assets](/docs/api-reference/assets/localized-assets)     | Contains information about uploading assets for your project locales using our asset upload API.                                                                                |
| [Embedded types](/docs/api-reference/assets/embedded-types)         | Contains information about embedding assets into the Rich Text field type using our asset upload API.                                                                           |

## Management SDK

| Document                                                                            | Contents                                                                                                                  |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [Overview](/docs/api-reference/management-sdk/management-sdk)                       | Contains information about Hygraph's Management SDK. Learn about its advantages and how it works.                         |
| [Quickstart](/docs/api-reference/management-sdk/management-sdk-quickstart)          | Contains our Management SDK Quickstart, with information on installation, and usage.                                      |
| [Migration](/docs/api-reference/management-sdk/management-sdk-quickstart#migrate-from-the-previous-sdk)            | Contains information on how to migrate from the previous SDK to the Management SDK.                                       |
| [Batch migration](/docs/api-reference/management-sdk/management-sdk-batchmigration) | Contains information on how to use the **Management SDK Method** for batch migrations.                                    |
| [Example](/docs/api-reference/management-sdk/management-sdk-example)              | An example of building a complete blog platform schema using the Management SDK. |
| [Method reference](/docs/api-reference/management-sdk/management-sdk-methods-reference)  | A quick reference for every operation that you can carry out using the Management SDK.                                   |

## Developer tools

| Document / Repos                                                                               | Contents                                                                               |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/rich-text" target="_blank">Rich text</Link>                                              | External link to our rich text renderer repo.                                          |
| <Link href="https://github.com/hygraph/rich-text/tree/main/packages/html-to-slate-ast" target="_blank">HTML to Slate AST</Link> | External link to our HTML to Slate AST converter for the Hygraph's RichTextAST format. |
| <Link href="https://github.com/hygraph/gatsby-source-graphcms" target="_blank">Gatsby Source Plugin</Link>                      | External link to our Gatsby Source Plugin.                                             |

&nbsp;

&nbsp;


---
# Management SDK

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk

The Hygraph Management SDK lets you programmatically manage your Hygraph project configuration, including schema, models, fields, taxonomies, workflows, webhooks, and editor UI elements. It provides a typed SDK that allows multiple schema-related actions to be **executed in order and in a single transaction**.

It is designed for automation and repeatability, enabling you to manage Hygraph configuration as code rather than through manual UI changes. Unlike the Content API, which handles data entry, the Management SDK defines the architecture of your project.

## Key benefits

The Management SDK is intended for use cases where manual configuration does not scale well. It enables you to:

- Apply multiple schema-related changes. It allows accepting a set of changes which are applied on an “all or none” basis. So if anything fails in one of the events along the process, everything is rolled back automatically.
- Bypass the web app, by allowing you to create a script that applies all the changes at once, without you having to procedurally create everything.
- Apply the scripts you create to different environments. So they can be used in test environments to test schema changes upfront. In this scenario, you would make all the schema changes in this migration script, test it, then apply the script to the master environment when everything works as intended.
- Store and review configuration changes in version control. Define schema and configuration changes as code and store them in a version control system alongside your application. This allows teams to review, audit, and apply changes consistently across environments using pull requests.
- Run migrations safely as part of CI/CD pipelines. Use the Management SDK in deployment pipelines to apply schema changes automatically before shipping dependent code. Batch migrations ensure changes are validated and applied atomically, reducing the risk of partial or inconsistent updates.

If you need to script or automate the Hygraph setup, the Management SDK is the recommended approach.

## How it works

The SDK works in two modes.

- **Write changes directly**: You initialize a client, call the methods that describe the schema you want, and then submit them to the Management server through the SDK. For more information, see the [quickstart guide](/docs/api-reference/management-sdk/management-sdk-quickstart).

- **Sync changes between environments**: If you have a development environment where you've already made and tested schema changes, you can generate a diff and apply it directly to another environment. This mode replaces the target schema. It does not merge changes. Any schema changes that exist in the target environment but not in the source will be deleted. For more information, see the [batch migration guide](/docs/api-reference/management-sdk/management-sdk-batchmigration).

In the above cases, the underlying method is the `submitBatchChanges` mutation. If any single change fails, the entire batch is rolled back automatically.

```ts
submitBatchChanges(data: BatchMigrationInput!): AsyncOperationPayload!
```

This mutation takes an `environmentId`, an optional name, and a list of changes as arguments, then executes them in a single transaction.

## What you can manage

The Management SDK covers project configuration, not content.

You can use it to manage:
- **Schema and models**: Models, fields, relations, remote fields
- **Taxonomies**: Taxonomies and hierarchical taxonomy nodes
- **Remote sources**: REST and GraphQL remote sources
- **Workflows**: Content workflows and workflow stages
- **Webhooks**: Webhook configuration and triggers
- **Editor UI**: System and custom sidebar elements

## When to use the SDK

Use the Management SDK when you need to:
- Automate schema changes
- Synchronize configuration between environments, such as `development`, `staging`, or `production`
- Run schema migrations during deployments
- Enforce consistency in large or distributed teams

## When not to use the SDK

The Management SDK is not intended for:

- Creating or updating content entries
- Editorial workflows
- Querying published content

For content operations, use the [Content API](/docs/api-reference#content-api).

## Next steps

- To get started, take a look at our [Quickstart](/docs/api-reference/management-sdk/management-sdk-quickstart).
- Learn how to [migrate from the old SDK](/docs/api-reference/management-sdk/management-sdk-quickstart#migrate-from-the-previous-sdk).


---
# Run batch migrations with the Management SDK

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-batchmigration

With batch migrations, you can apply multiple schema updates to an environment in a single operation.

This workflow uses the `Client.getEnvironmentDiff` method to get the diff, then submits all required schema changes at once. The migration either succeeds completely or fails entirely. If any step fails, no changes are applied. This reduces the risk of partial or inconsistent updates.

While supported and commonly used, submitting schema changes directly to production does not guarantee zero risk, especially when content already exists.

## How it works

Submitting batch changes is a two-step process:

1. **Generate a diff**: The Management SDK compares the source environment with a target environment using `getEnvironmentDiff` and produces a list of schema operations required to make the target match the source.

2. **Submit the diff as a single batch**: The generated diff is submitted using `applySchemaChanges`, which applies all operations together in a single action.

The batch either succeeds completely or fails entirely. If any operation fails validation or execution, the entire batch is rolled back.

<Alert theme="info">

This workflow is commonly recommended for customers, who have two environments by default, such as those on the Pro plan. It works on any plan where you have at least two environments.

</Alert>

### Supported schema elements

The following schema elements are supported for batch changes submissions:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - Models
        - Components
        - Locales
        - Simple fields
        - Conditional visibility in fields
        - Relational fields
        - Enumerations
        - Enumerable fields
        - Initial values in enumeration fields
      </div>
      <div className="flex-1">
        - Stages
        - Union fields
        - Apps
        - Custom renderers and app fields
        - Sidebar elements
        - Remote fields
        - Remote type definitions
        - Remote sources
      </div>
    </div>

<Alert theme="warning">**Not supported:** UI extensions.</Alert>

## Get the environment name

First, you need the environment name. For this query, you need to provide the project ID. You can find the Project ID in [Project settings](/docs/developer-guides/project/manage-project-info) or in the project URL - `https://app.hygraph.com/<projectId>/<environmentId>/`.

1. Navigate to the **API Playground** in your Hygraph project.
2. In the **API selector** dropdown, select the **Management API**.
3. Run the following query to get the environment names:

```graphql
query MyQuery {
  viewer {
    project(id: "<your-project-id>") {
      environments {
        name
        id
      }
    }
  }
}
```

## Create a Management SDK client

Create a new file, for example `submit-batch-changes.ts`, and initialize the client with the following parameters:

```ts
import { Client } from '@hygraph/management-sdk';

const client = new Client({
  authToken,
  endpoint,
  name, // optional
});
```

| Option                      | Description                                         |
|-----------------------------|-----------------------------------------------------|
| `authToken`                 | Permanent auth token for your project. This can be retrieved from your <Link href="https://app.hygraph.com/" target="_blank">Hygraph project</Link> in **Project Settings > Permanent Auth Tokens > Token**. Make sure the token has proper Management API permissions depending on what you plan to execute via the SDK.               |
| `endpoint`                  | Endpoint of the High Performance Content API that belongs to the environment that you will work with. The URL can be retrieved from your <Link href="https://app.hygraph.com/" target="_blank">Hygraph project</Link> in **Project Settings > Endpoints > High Performance Content API**.            |
| `name`                      | Optional identifier used for logging and debugging. Every migration has a unique name within an environment. If unspecified, a name will be generated and will be part of the response of a successful migration. Subsequent migrations with the same name in the same environment will fail.   |

For more information, [read this document](/docs/developer-guides/project/api-access).

## Generate a diff

Use the `getEnvironmentDiff` method to generate a list of operations required to make the target environment match the specified source environment.

In this example:
- The client is initialized with the `master` environment's auth token and endpoint. This is the target environment where changes will be applied.
- In the `getEnvironmentDiff` method, we pass `development` as the parameter. This is the source environment where changes come from.
- The result is a list of operations that will make `master` (target) match `development` (source).

```ts
const diff = await client.getEnvironmentDiff("development");
```

This returns operations to sync schema changes from `development` (source) to `master` (target).

### Required fields in diffs

When you make a field **required** in the source environment (`development`), existing content in the target environment (`master`) may contain `null` values for that field. To apply this change successfully, you must provide a migration value that replaces `null` for existing entries.

![Migration value in field validations](/images/docs/api-reference/schema/env-diffing-migrationvalue.png)

When generating a diff, the Management SDK suggests updating the field to `required`, but it does not automatically include a migration value. If you apply the diff without adding one, the operation will fail.

Before applying the diff, you must manually add a `migrationValue` to the corresponding change.

<Alert theme="info">

For boolean fields, use `true` or `false` as the migration value instead of a string.

</Alert>

```json
{
  "changes": [
    {
      "createSimpleField": {
        "apiId": "newField",
        "parentApiId": "Post",
        "type": "STRING",
        "displayName": "NewField",
        "description": null,
        "initialValue": null,
        "tableRenderer": "GCMS_SINGLE_LINE",
        "formRenderer": "GCMS_SINGLE_LINE",
        "tableExtension": null,
        "formExtension": null,
        "formConfig": {},
        "tableConfig": {},
        "isList": false,
        "isLocalized": false,
        "isRequired": true,
        "isUnique": false,
        "isHidden": false,
        "embeddableModels": [],
        "visibility": "READ_WRITE",
        "isTitle": false,
        "position": 3,
        "validations": null,
        "embedsEnabled": null,
        "migrationValue": "value"
      }
    }
  ]
}
```

The provided `migrationValue` replaces existing `null` values when batch changes are applied.

## Apply schema changes

Use the following method to schedule the generated diff for the target environment:

```ts
client.applySchemaChanges(diff);
```
This schedules all operations from the diff. 

## Dry run a migration

You can dry run your migration to preview what changes would be applied.

```ts
const changes = client.dryRun();

console.log(changes);
```

Inspect the `changes` array and validate the list of operations that will be applied to the target environment.

## Run a migration in production

The `run()` method executes the applied schema changes, making the target environment (`master`) match the source environment (`development`).

```ts
const result = await client.run(true);

if (result.errors) {
  console.log(result.errors);
} else {
  console.log(result.name);
}
```

## Full example

Here's a complete workflow showing source/target relationships. All schema changes from `development` (source) are applied to `master` (target), making `master` identical to `development`.

```ts
import { Client } from '@hygraph/management-sdk';

async function syncEnvironments() {
  // Create client for TARGET environment (where changes will be applied)
  const targetClient = new Client({
    authToken: '',
    endpoint: '',
    name: 'sync-dev-to-master'
  });

  // Generate diff from SOURCE environment (where changes come from)
  const diff = await targetClient.getEnvironmentDiff("development");

  // Apply schema changes to TARGET
  try {
    targetClient.applySchemaChanges(diff);
    const result = await targetClient.run(true);
    
    if (result.errors) {
      console.error('Migration failed with errors:', result.errors);
      return;
    }
    
    console.log('Successfully synced master to match development');
    console.log(`Migration name: ${result.name}`);
    console.log(`Finished at: ${result.finishedAt}`);
  } catch (error) {
    console.error('Migration failed:', error);
  }
}

syncEnvironments();
```

## How schema changes affect the target environment

Batch changes submitted with the Management SDK do not merge schemas. Instead, the target schema is replaced so that it exactly matches the source schema.

The SDK first generates a diff using `getEnvironmentDiff`, which lists the operations required to transform the target environment (`master`) into the source environment (`development`). When this diff is applied, schema elements are added, modified, or deleted as needed to achieve an exact match. Any schema elements present in `master` but missing or different in `development`, including models, fields, and sidebar elements, may be overwritten or deleted.

If a schema change exists only in `master`, the diff will include operations to remove or overwrite that change. To reduce the risk of unintended deletions or content loss:

- Freeze schema changes in `master` while working in `development`
- Keep schema changes mirrored across environments as you go
- Always review the generated diff before applying it

### Example scenarios

- You clone `master` to create `development`, make schema changes in `development`, and later make additional schema changes directly in `master`. When you generate and apply the diff, the SDK will suggest deleting the changes that exist only in `master`, because they are not present in `development`.

- A field named **Title Field** exists in both environments, but you rename it to **Title** only in `master`. The diff will suggest deleting **Title** and recreating **Title Field**, which aligns the schemas but results in content loss.

- You delete a field in `development` and then create a new field with the same name. The diff may not detect this as a deletion and recreation, even though the underlying field identity has changed.



---
# Complete example

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

This guide walks you through building a complete blog platform schema using the Management SDK. You'll create models, components, relations, enumerations, and configure conditional visibility.

## What you'll build

A blog platform with:

- `Post` model with title, content, status, and a featured flag
- `Author` model with name, bio, and email
- `Category` model with name and description
- `SeoMetadata` component (reusable SEO fields)
- `AuthorInfo` component (social media info)
- `CallToAction` and `ImageBlock` components (content blocks)
- Post-to-Author relation (many-to-one)
- Post-to-Category relation (many-to-many)
- Component embeddings (SEO in Post, social info in `Author`)
- Modular component field (flexible content blocks)
- Nested components (ContactDetails nested inside `AuthorInfo`)
- Status enumeration (`DRAFT`, `REVIEW`, `PUBLISHED`)
- Conditional visibility rules

## Prerequisites

Before you begin, ensure that you have the following:

- Hygraph project created
- [Permanent Auth Token](/docs/developer-guides/project/api-access#permanent-auth-tokens) with Management API permissions
- Node.js 18 or later installed
- Management SDK installed: `npm install @hygraph/management-sdk`
- Content API endpoint from **Project Settings > Endpoints > High Performance Content API**

## Dependency order

The Management SDK executes operations sequentially. You need to create dependencies before referencing them.

For example:
- Creating a relation before its target model exists will fail.
- Creating an enumerable field before its enumeration exists will fail.
- Embedding a component before it exists will fail.
- Nesting a component before the parent component exists will fail.

```

Create models (Author, Category, Post), and add simple fields to them
   ↓
Create enumerations (PostStatus)
   ↓
Add enumerable field (status) to Post
   ↓
Create components (SeoMetadata, AuthorInfo, CallToAction, ImageBlock), and add simple fields to them
   ↓
Embed components in models (SeoMetadata in Post, AuthorInfo in Author)
   ↓
Create nested components (ContactDetails nested inside AuthorInfo)
   ↓
Create modular component field (contentBlocks in Post)
   ↓
Create relations (Post→Author, Post→Category)
   ↓
Conditional visibility rules
```

## Initialize the client

Create the `create-blog-schema.ts` file:

```ts
import { Client } from '@hygraph/management-sdk';

const client = new Client({
  authToken: '',
  endpoint: '',
  name: 'create-blog-schema-v1', // Unique migration name
});

async function createBlogSchema() {
  try {
    // All operations will go here
  } catch (error) {
    console.error('Migration failed:', error);
    process.exit(1);
  }
}

createBlogSchema();
```

## Create models

Models must exist before you can add fields to them. The values of `apiId` and `apiIdPlural` must be different.

<Tabs>
  <TabsItem label="Author model">

```ts
// Create Author model
client.createModel({
  apiId: 'Author',
  apiIdPlural: 'Authors',
  displayName: 'Author',
  description: 'Blog post authors',
});

console.log('Created Author model');
```

  </TabsItem>
  <TabsItem label="Category model">

```ts
// Create Category model
client.createModel({
  apiId: 'Category',
  apiIdPlural: 'Categories',
  displayName: 'Category',
  description: 'Blog post categories',
});

console.log('Created Category model');
```

  </TabsItem>
  <TabsItem label="Post model">

```ts
// Create Post model
client.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
  displayName: 'Post',
  description: 'Blog posts',
});

console.log('Created Post model');
```

  </TabsItem>
</Tabs>

## Add fields to models

Now, you can add fields to your models. Note the following points:

- Only one field per model can be `isTitle: true`. This field appears as the entry identifier in the UI.
- `initialValue` sets the default for new entries.
- For boolean fields, use `true` or `false`.

<Tabs>
  <TabsItem label="Fields for Author model">

```ts
// Author: name (required, title field)
client.createSimpleField({
  parentApiId: 'Author',
  apiId: 'name',
  displayName: 'Name',
  type: SimpleFieldType.STRING,  // Use enum, not string
  isRequired: true,
  isTitle: true,
  visibility: VisibilityTypes.READ_WRITE,  // Optional but recommended
  description: 'Author full name',
});

// Author: email (required, unique)
client.createSimpleField({
  parentApiId: 'Author',
  apiId: 'email',
  displayName: 'Email',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  isUnique: true,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Author email address',
  validations: {
    String: {
      matches: {
        regex: '^([a-z0-9_\\.\\+-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$',
        errorMessage: 'Please enter a valid email address'
      }
    }
  }
});

// Author: bio (optional, rich text)
client.createSimpleField({
  parentApiId: 'Author',
  apiId: 'bio',
  displayName: 'Bio',
  type: SimpleFieldType.RICHTEXT,  // Use enum
  isRequired: false,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Author biography',
});

console.log('Added fields to Author');
```

  </TabsItem>
  <TabsItem label="Fields for Category model">

```ts
// Category: name (required, title field)
client.createSimpleField({
  parentApiId: 'Category',
  apiId: 'name',
  displayName: 'Name',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  isTitle: true,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Category name',
});

// Category: description
client.createSimpleField({
  parentApiId: 'Category',
  apiId: 'description',
  displayName: 'Description',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Category description',
});

console.log('Added fields to Category');
```

  </TabsItem>
  <TabsItem label="Fields for Post model">

```ts
// Post: title (required, title field)
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'title',
  displayName: 'Title',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  isTitle: true,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Post title',
});

// Post: slug (required, unique)
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'slug',
  displayName: 'Slug',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  isUnique: true,
  tableRenderer: 'GCMS_SLUG',
  formRenderer: 'GCMS_SLUG',
  visibility: VisibilityTypes.READ_WRITE,
  description: 'URL-friendly slug',
});

// Post: content (rich text)
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'content',
  displayName: 'Content',
  type: SimpleFieldType.RICHTEXT,  // Use enum
  isRequired: false,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Post content',
});

// Post: excerpt (optional)
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'excerpt',
  displayName: 'Excerpt',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Short summary for listings',
});

// Post: featured (boolean, default false)
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'featured',
  displayName: 'Featured',
  type: SimpleFieldType.BOOLEAN,  // Use enum
  isRequired: true,
  initialValue: 'false',  // String, not boolean!
  visibility: VisibilityTypes.READ_WRITE,
  description: 'Show in featured section',
});

console.log('Added fields to Post');
```

  </TabsItem>
</Tabs>

## Create an enumeration

Create an enumeration before configuring fields that reference them.

```ts
// Create PostStatus enumeration
client.createEnumeration({
  apiId: 'PostStatus',
  displayName: 'Post Status',
  description: 'Workflow status for blog posts',
  values: [
    { apiId: 'DRAFT', displayName: 'Draft' },
    { apiId: 'REVIEW', displayName: 'In Review' },
    { apiId: 'PUBLISHED', displayName: 'Published' },
  ],
});

console.log('Created PostStatus enumeration');
```

## Add enumeration to model

The enumeration, `PostStatus`, must already exist. The `initialValue` must match one of the enumeration's values.

```ts
// Post: status (enumerable field)
client.createEnumerableField({
  parentApiId: 'Post',
  apiId: 'status',
  displayName: 'Status',
  enumerationApiId: 'PostStatus',
  isRequired: true,
  initialValue: 'DRAFT',
  description: 'Publication status',
});

console.log('Added status enumeration to Post');
```

## Create components

Components are reusable field groups that can be embedded in multiple models. Create components before embedding them in models.

<Tabs>
  <TabsItem label="SEO Metadata component">

```ts
// Create SEO Metadata component
client.createComponent({
  apiId: 'SeoMetadata',
  apiIdPlural: 'SeoMetadatas',
  displayName: 'SEO Metadata',
  description: 'Search engine optimization fields',
});

console.log('Created SeoMetadata component');

// Add fields to the component
client.createSimpleField({
  parentApiId: 'SeoMetadata',
  apiId: 'metaTitle',
  displayName: 'Meta Title',
  type: SimpleFieldType.STRING,  // Use enum, not string
  isRequired: false,
  description: 'SEO title tag',
  validations: {
    String: {  // Wrap in String object
      characters: {
        max: 60,
        errorMessage: 'Meta title should be under 60 characters',
      },
    },
  },
});

client.createSimpleField({
  parentApiId: 'SeoMetadata',
  apiId: 'metaDescription',
  displayName: 'Meta Description',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  formRenderer: 'GCMS_MULTILINE',
  description: 'SEO meta description',
  validations: {
    String: {  // Wrap in String object
      characters: {
        max: 160,
        errorMessage: 'Meta description should be under 160 characters',
      },
    },
  },
});

client.createSimpleField({
  parentApiId: 'SeoMetadata',
  apiId: 'keywords',
  displayName: 'Keywords',
  type: SimpleFieldType.STRING,  // Use enum
  isList: true,
  isRequired: false,
  description: 'SEO keywords',
});

client.createSimpleField({
  parentApiId: 'SeoMetadata',
  apiId: 'noIndex',
  displayName: 'No Index',
  type: SimpleFieldType.BOOLEAN,  // Use enum
  isRequired: true,
  initialValue: 'false',  // String value, not boolean
  description: 'Prevent search engine indexing',
});

console.log('Added fields to SeoMetadata component');
```

  </TabsItem>
  <TabsItem label="AuthorInfo component">

```ts
// Create AuthorInfo component for flexible author details
client.createComponent({
  apiId: 'AuthorInfo',
  apiIdPlural: 'AuthorInfos',
  displayName: 'Author Info',
  description: 'Additional author information',
});

client.createSimpleField({
  parentApiId: 'AuthorInfo',
  apiId: 'website',
  displayName: 'Website',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  description: 'Author website URL',
});

client.createSimpleField({
  parentApiId: 'AuthorInfo',
  apiId: 'twitter',
  displayName: 'Twitter Handle',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  description: 'Twitter username',
});

client.createSimpleField({
  parentApiId: 'AuthorInfo',
  apiId: 'location',
  displayName: 'Location',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  description: 'Author location',
});

console.log('Created AuthorInfo component');
```

  </TabsItem>
  <TabsItem label="CallToAction component">

```ts
// Create components for page builder
client.createComponent({
  apiId: 'CallToAction',
  apiIdPlural: 'CallToActions',
  displayName: 'Call to Action',
  description: 'CTA block with button',
});

client.createSimpleField({
  parentApiId: 'CallToAction',
  apiId: 'heading',
  displayName: 'Heading',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  description: 'CTA heading',
});

client.createSimpleField({
  parentApiId: 'CallToAction',
  apiId: 'buttonText',
  displayName: 'Button Text',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  description: 'Button label',
});

client.createSimpleField({
  parentApiId: 'CallToAction',
  apiId: 'buttonUrl',
  displayName: 'Button URL',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  description: 'Button destination URL',
});

console.log('Created CallToAction component');
```

  </TabsItem>
  <TabsItem label="ImageBlock component">

```ts
// Create components for page builder
client.createComponent({
  apiId: 'ImageBlock',
  apiIdPlural: 'ImageBlocks',
  displayName: 'Image Block',
  description: 'Image with caption',
});

client.createSimpleField({
  parentApiId: 'ImageBlock',
  apiId: 'imageUrl',
  displayName: 'Image URL',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  description: 'Image source URL',
});

client.createSimpleField({
  parentApiId: 'ImageBlock',
  apiId: 'caption',
  displayName: 'Caption',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: false,
  description: 'Image caption',
});

client.createSimpleField({
  parentApiId: 'ImageBlock',
  apiId: 'altText',
  displayName: 'Alt Text',
  type: SimpleFieldType.STRING,  // Use enum
  isRequired: true,
  description: 'Accessibility text',
});

console.log('Created ImageBlock component');
```

  </TabsItem>
</Tabs>

## Embed component in model

Now let's embed the SEO component into the `Post` model. You can add SEO metadata to each post without duplicating fields across models.

```ts
// Post: Embed SeoMetadata component
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'seo',
  displayName: 'SEO',
  componentApiId: 'SeoMetadata',
  isRequired: false,
  isList: false,
  description: 'SEO metadata for search engines',
});

console.log('Embedded SEO component in Post');
```

## Create modular component field

Modular components allow editors to choose from multiple component types, perfect for page builders. Editors can now add multiple `CallToAction` and `ImageBlock` components in any order within a post. A post might have:
- `ImageBlock`: A hero image or an infographic
- `CallToAction`: Subscribe prompt or download guide

```ts
// Post: Content blocks (modular component)
client.createComponentUnionField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  componentApiIds: ['CallToAction', 'ImageBlock'],
  isList: true,
  isRequired: false,
  description: 'Flexible content blocks for rich posts',
});

console.log('Created modular component field');
```

## Create nested components

Components can be nested inside other components for deeply hierarchical structures. Let's create a nested `Address` component. In this example, notice `parentApiId: 'AuthorInfo'`. We're nesting a component inside another component, not inside a model. This creates a two-level hierarchy: `Author → AuthorInfo → ContactDetails`.

```ts
// Create child component
client.createComponent({
  apiId: 'ContactDetails',
  apiIdPlural: 'ContactDetailsCollection',
  displayName: 'Contact Details',
  description: 'Phone and email contact information',
});

// Add fields to the component
client.createSimpleField({
  parentApiId: 'ContactDetails',
  apiId: 'phone',
  displayName: 'Phone',
  type: SimpleFieldType.STRING,
  isRequired: false,
  description: 'Contact phone number',
  visibility: VisibilityTypes.READ_WRITE
});

client.createSimpleField({
  parentApiId: 'ContactDetails',
  apiId: 'email',
  displayName: 'Email',
  type: SimpleFieldType.STRING,
  isRequired: true,  // Email is required
  description: 'Contact email address',
  validations: {
    String: {
      matches: {
        regex: '^([a-z0-9_\\.\\+-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$',
        errorMessage: 'Please enter a valid email address'
      }
    }
  }
});

console.log('Created ContactDetails component');

// Nest ContactDetails inside AuthorInfo component
client.createComponentField({
  parentApiId: 'AuthorInfo',
  apiId: 'contact',
  displayName: 'Contact',
  componentApiId: 'ContactDetails',
  isRequired: false,
  isList: false,  // Single contact (or true for multiple)
  description: 'Contact information',
  visibility: VisibilityTypes.READ_WRITE
});

console.log('Nested ContactDetails inside AuthorInfo');
```

**Result structure:**

```
Author (model)
  └── AuthorInfo (component)
    ├── website (STRING field)
    ├── twitter (STRING field)
    ├── location (STRING field)
    └── contact (component field) ← NESTED
        └── ContactDetails (component)
            ├── phone (STRING field)
            └── email (STRING field)
```

## Create a many-to-one reference

One author can write multiple posts. For this use case, we need to create a **many-to-one** relation.

```ts
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'author',
  displayName: 'Author',
  type: RelationalFieldType.RELATION,  // Use enum, not string
  reverseField: {
    apiId: 'posts',
    modelApiId: 'Author',  // Required! Specify the related model
    displayName: 'Posts',
    isList: true,  // Required! Author has many posts
    visibility: VisibilityTypes.READ_WRITE  // Use visibility instead of isHidden
  },
  isList: false,  // Post has one author
  isRequired: false,  // Cannot be required for RELATION type (only ASSET)
  description: 'Post author'
});

console.log('Created Post→Author relation');
```

## Create a many-to-many reference

A post can belong to multiple categories. A category can have multiple posts. For this use case, we need to create a **many-to-many** relation.

```ts
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'categories',
  displayName: 'Categories',
  type: RelationalFieldType.RELATION,  // Use enum, not string
  reverseField: {
    apiId: 'posts',
    modelApiId: 'Category',  // Required! Specify the related model here
    displayName: 'Posts',
    isList: true,  // Required! Category has many posts
    visibility: VisibilityTypes.READ_WRITE  // Use visibility instead of isHidden
  },
  isList: true,
  isRequired: false,
  description: 'Post categories'
});

console.log('Created Post→Category relation');
```

## Add conditional visibility

Make the `excerpt` field required only when `status` is `PUBLISHED`. Otherwise, it remains optional.

```ts
client.updateSimpleField({
  apiId: "excerpt",
  parentApiId: "Post",
  isRequired: true,
  visibility: VisibilityTypes.READ_WRITE,
  visibilityCondition: {
    baseField: "status", // API ID of the enumerable field (not the enum name)
    operator: FieldConditionOperator.IS,
    enumerationValues: ["PUBLISHED"],
    booleanValue: null
  }
});

console.log('Configured conditional visibility on excerpt');
```

## Advanced features

### Add a taxonomy

Taxonomies organize content into hierarchical categories. Let's add a category taxonomy and add the taxonomy to the `Post` model. Posts can now be organized using a hierarchical category tree.

```ts
// Create the taxonomy with all nodes at once
client.createTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Blog Categories',
  description: 'Hierarchical blog categorization',
  taxonomyNodes: [
    // Top-level categories (parent: null)
    { apiId: 'technology', displayName: 'Technology', parent: null },
    { apiId: 'business', displayName: 'Business', parent: null },
    // Subcategories
    { apiId: 'webDev', displayName: 'Web Development', parent: 'technology' },
    { apiId: 'aiMl', displayName: 'AI & Machine Learning', parent: 'technology' }
  ]
});

// Add taxonomy field to Post model
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'taxonomyCategories',
  displayName: 'Taxonomy Categories',
  taxonomyApiId: 'BlogCategories',
  isList: true,
  isRequired: false,
  description: 'Hierarchical categorization'
});

console.log('Created taxonomy and taxonomy field');

```

### Add a workflow

Create an editorial workflow for content approval. Posts can move through the draft → review → approved stages before publication.

```ts
client.createWorkflow({
  apiId: 'editorialWorkflow',
  displayName: 'Editorial Workflow',
  description: 'Content review and approval process',
  enabled: true,  // Required!
  steps: [  // Not "stages"!
    {
      apiId: 'draft',
      displayName: 'Draft',
      description: 'Work in progress',
      color: ColorPalette.BLUE,  // Use enum, not string
      allowEdit: true,  // Required!
      allowedRoles: ['role-id-1'],  // Required! Array of role IDs
      position: 0
    },
    {
      apiId: 'review',
      displayName: 'In Review',
      description: 'Awaiting editorial review',
      color: ColorPalette.YELLOW,  // Use enum
      allowEdit: false,  // Required!
      returnToStep: 'draft',  // Can return to draft if rejected
      allowedRoles: ['role-id-2'],  // Required!
      position: 1
    },
    {
      apiId: 'approved',
      displayName: 'Approved',
      description: 'Ready for publication',
      color: ColorPalette.GREEN,  // Use enum
      allowEdit: false,  // Required!
      allowedRoles: ['role-id-3'],  // Required!
      publishStages: ['published'],  // Optional: stages that can be published from this step
      position: 2
    },
  ],
});

console.log('Created editorial workflow');

```

### Add a webhook

Notify external systems when posts are published. Marketing system receives notifications when posts are published.

```ts
client.createWebhook({
  name: 'Post Publish Notification',
  description: 'Notify marketing system when blog posts are published',
  url: 'https://api.marketing.example.com/webhooks/blog-published',
  method: WebhookMethod.POST,
  headers: {
    Authorization: 'Bearer webhook-secret-token',
    'Content-Type': 'application/json',
  },
  isActive: true,
  includePayload: true,
  models: [],  // Empty array = all models (including future ones)
  stages: [],  // Empty array = all stages (including future ones)
  triggerType: WebhookTriggerType.CONTENT_MODEL,
  triggerActions: [WebhookTriggerAction.PUBLISH],
  secretKey: 'webhook-secret-key'
});
```

## Test with dry run

Before applying changes to production, test the migration:

```ts
// At the start of createBlogSchema(), before try block:
const changes = client.dryRun();

console.log('=== DRY RUN RESULTS ===');
console.log(`Operations: ${changes.length}`);
console.log(JSON.stringify(changes, null, 2));
console.log('======================');

// Exit without running
process.exit(0);
```

Review the output to ensure all operations are correct. Then remove the dry run code and proceed to production.

## Run the migration

```ts
async function createBlogSchema() {
  try {
    // ... all operations here ...

    // Execute migration
    const result = await client.run(true);

    if (result.errors) {
      console.error('Migration failed with errors:', result.errors);
      process.exit(1);
    }

    console.log('Migration completed successfully');
    console.log(`Migration name: ${result.name}`);
    console.log(`Finished at: ${result.finishedAt}`);
  } catch (error) {
    console.error('Migration failed:', error);
    process.exit(1);
  }
}
```

Run the script:

```bash
export HYGRAPH_AUTH_TOKEN="your-token"
export HYGRAPH_ENDPOINT="https://your-region.hygraph.com/v2/..."
node create-blog-schema.ts
```

## Integration test

Test the complete workflow:

1. **Create Author** with social info and nested contact details
2. **Create Categories**
3. **Create Post** with all features:
   - Set status to DRAFT (excerpt optional)
   - Fill in title, slug, content, featured flag
   - Select author and categories (relations)
   - Select taxonomy categories (hierarchical)
   - Add SEO metadata (metaTitle, metaDescription, keywords)
   - Add content blocks (CallToAction and ImageBlock components)
4. **Test conditional visibility:** Change status to PUBLISHED, verify excerpt becomes required
5. **Test workflow:** Move through stages if configured
6. **Test webhook:** Publish post and verify notification sent
7. **Verify final result:** Post displays with author (nested contact), categories, taxonomy, SEO, content blocks, and all features working together

## Troubleshooting

### Wrong operation order

Operations must be executed in the correct order. For example, creating a relation before the target model exists will fail.

<Tabs>
  <TabsItem label="Incorrect">

```ts
client.createRelationalField({
  parentApiId: 'Post',
  relatedModelApiId: 'Author', // Author doesn't exist yet
  // ...
});
client.createModel({ apiId: 'Author' /* ... */ });
```

  </TabsItem>
  <TabsItem label="Correct">

```ts
client.createModel({ apiId: 'Author' /* ... */ });
client.createRelationalField({
  parentApiId: 'Post',
  relatedModelApiId: 'Author', // Author exists now
  // ...
});
```

  </TabsItem>
</Tabs>

### Reused migration names

Use unique names for each migration, such as `create-blog-schema-v1`, `create-blog-schema-v2`, etc. Reusing names will cause the migration to fail.

```ts
const client = new Client({
  name: 'create-blog-schema', // First run: OK
  // Second run with same name: FAILS
});
```

### apiId and apiIdPlural are the same

The values of `apiId` and `apiIdPlural` of a model must be different.

<Tabs>
  <TabsItem label="Wrong">

```ts
client.createModel({
  apiId: 'Post',
  apiIdPlural: 'Post', // Must differ
});
```

  </TabsItem>
  <TabsItem label="Correct">

```ts
client.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
});
```

  </TabsItem>
</Tabs>

### Multiple title fields in a model

You can only have one `isTitle: true` field per model. This field is used as the entry identifier in the UI.

<Tabs>
  <TabsItem label="Wrong">

```ts
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'title',
  isTitle: true, // First title field - OK
});
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'name',
  isTitle: true, // Second title field - FAILS
});
```

  </TabsItem>
  <TabsItem label="Correct">

```ts
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'title',
  isTitle: true, // First title field - OK
});
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'name',
});
```

  </TabsItem>
</Tabs>

## Next steps

Review the [Methods Reference](/docs/api-reference/management-sdk/management-sdk-methods-reference) for all available Management SDK operations.


---
# Management SDK methods reference

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-methods-reference

This document is a quick reference for every operation that you can carry out using the Management SDK. For a tutorial-style guide, see [this document](/docs/api-reference/management-sdk/management-sdk-example).

All `Create`, `Update`, and `Delete` actions require **Update and Delete Existing Fields** permissions set in the Permanent Auth Token.

## Important notes

**Data loss warnings:**
- Converting fields to/from lists (`isList`) may cause data loss for existing entries.
- Changing `isRequired` to true requires `migrationValue` for existing entries with null values.
- Using `isUnique` with `initialValue` or `migrationValue` is forbidden (unique values must differ per entry).
- Converting field types may result in data loss or validation failures.

**Cardinality (Relational fields):**
- Relation cardinality is set at creation and cannot be changed later.
- `isList: false` + reverse `isList: false` = one-to-one.
- `isList: false` + reverse `isList: true` = one-to-many.
- `isList: true` + reverse `isList: true` = many-to-many.
- For components: reverse side must have `isList: true` to allow reconnection.

**Naming conventions:**
- Models/components: `PascalCase` (Examples: `BlogPost`, `SeoMetadata`)
- Fields: `camelCase` (Examples: `title`, `publishedAt`)
- Enumerations: `PascalCase` (Examples: `PostStatus`)
- Enum values: `UPPER_SNAKE_CASE` (Examples: `DRAFT`, `PUBLISHED`)

## Supported operations

All operations that can be executed by the SDK are listed in the TypeScript Type Definitions, <Link href="https://unpkg.com/@hygraph/management-sdk@latest/dist/src/Client.d.ts" target="_blank">Client.d.ts</Link> file.

## Models

### createModel()

Creates a new content model.

**Use cases:**
- Setting up new content types for your application, such as `BlogPost`, `Product`, `Author`.
- Creating models for different content sections, such as `Pages`, `Articles`, `Events`.
- Initializing models with custom sidebar elements from apps, such as `Analytics Dashboard`, `Content Workflows`, `Variants`.

**Important notes:**
- `apiId` and `apiIdPlural` must be different (cannot be the same value).
- `apiId` must be PascalCase and start with uppercase letter.
- Models must have unique `apiId` and `displayName` within an environment.
- Cannot create required fields on system models/components.
- Sidebar elements can be added during creation or via `updateModel`.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createModel({
  apiId: string,                    // Required: The model API ID
  apiIdPlural: string,              // Required: The plural API ID (used for lists)
  displayName: string,               // Required: Display name shown in the webapp
  description?: string,             // Optional: Description of the model
  isSystem?: boolean,               // Optional: Only AppTokens should provide this flag
  sidebarElements?: Array<{         // Optional: Sidebar elements to create
    displayName: string,             // Required: Display name for the sidebar element
    description?: string,           // Optional: Description for the sidebar element
    config?: JSON,                  // Optional: JSON metadata associated with the sidebar element
    appElementApiId: string,        // Required: API ID of the App element
    appApiId: string,               // Required: API ID of the App
    position?: number               // Optional: Position of the sidebar element
  }>
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic model creation
client.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
  displayName: 'Blog Post',
  description: 'Blog posts for the website',
});

// Model with custom sidebar elements
client.createModel({
  apiId: 'Product',
  apiIdPlural: 'Products',
  displayName: 'Product',
  description: 'E-commerce products',
  sidebarElements: [
    {
      displayName: 'Product Analytics',
      description: 'View product analytics',
      appElementApiId: 'analytics-dashboard',
      appApiId: 'analytics-app',
      position: 0,
      config: { refreshInterval: 30 },
    },
  ],
});
```

  </TabsItem>
</Tabs>

### updateModel()

Updates an existing content model.

**Use cases:**
- Renaming models (using `newApiId`).
- Updating model descriptions or display names
- Managing sidebar elements (adding, updating, removing custom and system sidebar elements).
- Adding app integrations to models.

**Important notes:**
- Renaming with newApiId updates all references to the model.
- Sidebar elements can be managed via sidebarElementsToUpsert structure.
- System sidebar elements include: `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`.
- Custom sidebar elements require `appApiId` and `appElementApiId`.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateModel({
  apiId: string,                    // Required: Current API ID of the model
  newApiId?: string,                // Optional: New API ID (to rename the model)
  apiIdPlural?: string,             // Optional: New plural API ID
  displayName?: string,              // Optional: New display name
  description?: string,              // Optional: New description
  isSystem?: boolean,                // Optional: System model flag (only for AppTokens)
  sidebarElementsToUpsert?: {       // Optional: Sidebar elements to create/update/delete
    customSidebarElementsToCreate?: Array<{
      displayName: string,           // Required: Display name
      description?: string,          // Optional: Description
      config?: JSON,                 // Optional: JSON metadata
      appElementApiId: string,       // Required: API ID of the App element
      appApiId: string,              // Required: API ID of the App
      position?: number              // Optional: Position
    }>,
    systemSidebarElementsToCreate?: Array<{
      type: SystemSidebarElementType, // Required: System sidebar element type
      config?: JSON,                 // Optional: JSON metadata
      position?: number              // Optional: Position
    }>,
    sidebarElementsToUpdate?: Array<{
      displayName: string,           // Required: Current display name (identifier)
      newDisplayName?: string,       // Optional: New display name
      description?: string,          // Optional: New description
      config?: JSON,                 // Optional: New config
      position?: number              // Optional: New position
    }>,
    customSidebarElementsToDelete?: Array<{
      appApiId: string,              // Required: API ID of the App
      appElementApiId: string        // Required: API ID of the App element
    }>,
    systemSidebarElementsToDelete?: Array<{
      type: SystemSidebarElementType // Required: System sidebar element type
    }>
  }
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename model and change display name
client.updateModel({
  apiId: 'Post',
  newApiId: 'BlogPost',
  displayName: 'Blog Post',
  description: 'Updated description',
});

// Update with sidebar elements management
client.updateModel({
  apiId: 'Product',
  displayName: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToCreate: [
      {
        displayName: 'Product Analytics',
        description: 'View analytics',
        appElementApiId: 'analytics-dashboard',
        appApiId: 'analytics-app',
        position: 0,
      },
    ],
    systemSidebarElementsToCreate: [
      {
        type: SystemSidebarElementType.INFORMATION,
        position: 1,
      },
    ],
    sidebarElementsToUpdate: [
      {
        displayName: 'Product Analytics',
        newDisplayName: 'Analytics Dashboard',
        description: 'Updated analytics dashboard',
        position: 2,
      },
    ],
    customSidebarElementsToDelete: [
      {
        appApiId: 'old-app',
        appElementApiId: 'old-element',
      },
    ],
    systemSidebarElementsToDelete: [
      {
        type: SystemSidebarElementType.VERSIONS,
      },
    ],
  },
});
```

  </TabsItem>
</Tabs>

- `SystemSidebarElementType` - `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`

### deleteModel()

Deletes a content model.

**Use cases:**
- Removing unused content models.
- Cleaning up test/development models.
- Restructuring content architecture.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all entries in the model.
- Deletes all fields associated with the model.
- Delete the model only if there are no other models that depend on it.

<Tabs>
  <TabsItem label="Parameter">

```ts
client.deleteModel({
  apiId: string  // Required: The API ID of the model to delete
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a model
client.deleteModel({
  apiId: 'Post',
});

console.log('Model deleted');
```

  </TabsItem>
</Tabs>

## Simple fields

### createSimpleField()

Creates a simple field on a model or component.

**Use cases:**
- Adding text fields (title, description, content), such as `title`, `description`, `content` in the `Post` model .
- Creating date/time fields (publishedAt, eventDate), such as `publishedAt`, `eventDate` in the `Post` model.
- Setting up boolean flags (featured, published, active), such as `featured`, `published`, `active` in the `Post` model.
- Creating numeric fields (price, rating, count), such as `price`, `rating`, `count` in the `Post` model.
- Adding rich text content fields, such as `content` in the `Post` model.
- Creating slug fields with auto-generation, such as `slug` in the `Post` model.
- Setting up email/URL fields with validation, such as `email`, `url` in the `Post` model.
- Creating hidden fields for internal tracking, such as `internalTracking` in the `Post` model.

**Important notes:**
- Field `apiId` must be camelCase and start with lowercase letter.
- Reserved field names: `createdAt`, `createdBy`, `documentInStages`, `history`, `id`, `locale`, `localizations`, `publish`, `publishedAt`, `publishedBy`, `status`, `updatedAt`, `updatedBy`, `versions`.
- `isUnique: true` cannot be combined with `initialValue` or `migrationValue`.
- RichText fields cannot be marked as title (`isTitle: true`).
- List RichText fields cannot be required (`isList: true + isRequired: true`).
- ID type fields are validated as CUIDs and stored as `varchar(25)`.
- `initialValue` must be stringified for non-string types (e.g., `'false'` for boolean).

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createSimpleField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model/component (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  type: SimpleFieldType,            // Required: Field type enum
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  initialValue?: string,            // Optional: Default value (stringified for non-strings)
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,           // Optional: Form renderer identifier. Supported values: `GCMS_SINGLE_LINE`, `GCMS_MULTI_LINE`, `GCMS_SLUG`, or `GCMS_MARKDOWN`
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                  // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized (default: false)
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing existing field to true, must provide migrationValue
  isUnique?: boolean,               // Optional: Whether field is unique (default: false)
                                    // CANNOT be combined with initialValue or migrationValue
                                    // Unique values must differ per entry
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title (default: false)
  position?: number,                // Optional: Field position
  validations?: {                   // Optional: Field validations with custom error messages
    Int?: {
      range?: {                     // Validate numeric range
        min?: number,               // Minimum value (inclusive)
        max?: number,               // Maximum value (inclusive)
        errorMessage?: string       // Custom error shown to users
      },
      listItemCount?: {             // Validate list length (when isList is true)
        min?: number,               // Minimum items required
        max?: number,               // Maximum items allowed
        errorMessage?: string
      }
    },
    String?: {
      characters?: {                // Validate string length
        min?: number,               // Minimum characters
        max?: number,               // Maximum characters
        errorMessage?: string
      },
      matches?: {                   // Validate with regex pattern (must match)
        regex: string,              // Regex pattern (e.g., email format)
        flags?: string[],           // Regex flags (e.g., ['i'] for case-insensitive)
        errorMessage?: string
      },
      notMatches?: {                // Validate with regex pattern (must NOT match)
        regex: string,              // Regex pattern to reject
        flags?: string[],
        errorMessage?: string
      }
    }
  },
  migrationValue?: string,          // Optional: Value to set for existing null entries
                                    // Required when changing isRequired to true on existing fields
                                    // Cannot be combined with isUnique (unique values must differ per entry)
  embedsEnabled?: boolean,          // Optional: Enable rich text embeds
  embeddableModels?: string[],     // Required when embedsEnabled is true
                                    // Array of model API IDs that can be embedded
  visibilityCondition?: {           // Optional: Conditional visibility - show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic string field
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'title',
  displayName: 'Title',
  type: SimpleFieldType.STRING,
  isRequired: true,
  isTitle: true,
});

// String field with validations
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'slug',
  displayName: 'Slug',
  type: SimpleFieldType.STRING,
  isRequired: true,
  isUnique: true,
  validations: {
    String: {
      characters: { max: 100, errorMessage: 'Slug must be under 100 characters' },
      matches: { regex: '^[a-z0-9-]+$', flags: [], errorMessage: 'Invalid slug format' },
    },
  },
});

// Slug field with validations
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.STRING,
  apiId: 'slug',
  displayName: 'Slug',
  description: 'Enter the slug for this page, such as about, blog, or contact',
  isRequired: true,
  isUnique: true,
  tableRenderer: 'GCMS_SLUG',
  formRenderer: 'GCMS_SLUG',
  validations: {
    String: {
      characters: {
        max: 100,
        errorMessage: 'Slug must be under 100 characters'
      },
      matches: {
        regex: '^[a-z0-9-]+$',
        flags: [],
        errorMessage: 'Slug can only contain lowercase letters, numbers, and hyphens'
      },
    },
  },
});

// Richtext field
client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.RICHTEXT,
  apiId: '<api_id>',
  displayName: '<Display Name>',
  description:
    '<Enter the content for this page. The content uses the rich-text editor.>',
  isRequired: true,
});

// Rich text field with embeds
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'content',
  displayName: 'Content',
  type: SimpleFieldType.RICHTEXT,
  embedsEnabled: true,
  embeddableModels: ['Author', 'Image'],
});

// Boolean field with initial value
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'featured',
  displayName: 'Featured',
  type: SimpleFieldType.BOOLEAN,
  isRequired: true,
  initialValue: 'false', // Must be stringified
});

// Hidden integer field with custom field validation
client.createSimpleField({
  parentApiId: 'Product',
  type: SimpleFieldType.INT,
  apiId: 'viewCount',
  displayName: 'View Count',
  visibility: VisibilityTypes.HIDDEN,
  validations: {
    Int: {
      range: {
        max: 1000,
        min: 0,
        errorMessage: 'Counter has to be between 0 and 1000',
      },
    },
  },
});

// Required and unique email field with validation
client.createSimpleField({
  parentApiId: 'User',
  type: SimpleFieldType.STRING,
  apiId: 'email',
  displayName: 'Email',
  description: 'User email address',
  isRequired: true,
  isUnique: true,
  validations: {
    String: {
      matches: {
        regex: '^([a-z0-9_\\.\\+-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$',
        flags: ['i'], // Case-insensitive matching
        errorMessage: 'Please enter a valid email address',
      },
    },
  },
});

// Create a list of date times for event dates
client.createSimpleField({
  parentApiId: 'Post',
  type: SimpleFieldType.DATETIME,
  apiId: 'scheduledPublishDates',
  displayName: 'Scheduled Publish Dates',
  description: 'Multiple dates when this post should be published',
  isRequired: false,
  isList: true,
});

// Add a field to a component
client.createSimpleField({
  parentApiId: 'SeoMetadata',
  type: SimpleFieldType.STRING,
  apiId: 'metaTitle',
  displayName: 'Meta Title',
});
```

  </TabsItem>
</Tabs>

**Enums**

- `SimpleFieldType`: `ID`, `STRING`, `RICHTEXT`, `INT`, `FLOAT`, `BOOLEAN`, `JSON`, `DATETIME`, `DATE`, `LOCATION`, `COLOR`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateSimpleField()

Updates an existing simple field.

**Use cases:**
- Renaming fields
- Adding/updating validations
- Changing field visibility
- Updating embeddable models for rich text fields
- Adding conditional visibility
- Changing required/unique status

**Important notes:**
- Field type cannot be changed (immutable).
- `embeddableModels` uses add/remove structure: `{ modelsToAdd: [], modelsToRemove: [] }`.
- When changing `isRequired` to true, must provide `migrationValue` for existing null entries.
- Cannot change `isList` without potential data loss.
- `visibilityCondition` can be set to `null` to remove it.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateSimpleField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model/component API ID (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique
                                    // CANNOT be used with initialValue or migrationValue
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title
  position?: number,                // Optional: Field position
  initialValue?: string,            // Optional: Default value (stringified)
  migrationValue?: string,          // Optional: Migration value for existing data
                                    // Required when changing isRequired to true on existing fields
  validations?: {                   // Optional: Field validations (same structure as create)
    Int?: {
      range?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      listItemCount?: {
        min?: number,
        max?: number,
        errorMessage?: string
      }
    },
    Float?: {
      range?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      listItemCount?: {
        min?: number,
        max?: number,
        errorMessage?: string
      }
    },
    String?: {
      characters?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      listItemCount?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      matches?: {
        regex: string,
        flags?: string[],
        errorMessage?: string
      },
      notMatches?: {
        regex: string,
        flags?: string[],
        errorMessage?: string
      }
    }
  },
  embedsEnabled?: boolean,          // Optional: Enable rich text embeds
  embeddableModels?: {              // Optional: Manage embeddable models (different from create)
    modelsToAdd?: string[],         // Model API IDs to add to existing list
    modelsToRemove?: string[]       // Model API IDs to remove from existing list
  },                                 // NOTE: Different structure from create!
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,           // Optional: Form renderer identifier. Supported values: `GCMS_SINGLE_LINE`, `GCMS_MULTI_LINE`, `GCMS_SLUG`, or `GCMS_MARKDOWN`
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename field and change display name
client.updateSimpleField({
  apiId: 'title',
  newApiId: 'postTitle',
  displayName: 'Post Title',
});

// Update validations
client.updateSimpleField({
  apiId: 'slug',
  validations: {
    String: {
      characters: { max: 150, errorMessage: 'Slug must be under 150 characters' },
    },
  },
});

// Update embeddable models (add/remove models)
client.updateSimpleField({
  apiId: 'content',
  embedsEnabled: true,
  embeddableModels: {
    modelsToAdd: ['Video', 'Quote'],
    modelsToRemove: ['Image'],
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `SimpleFieldType`: `ID`, `STRING`, `RICHTEXT`, `INT`, `FLOAT`, `BOOLEAN`, `JSON`, `DATETIME`, `DATE`, `LOCATION`, `COLOR`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### deleteField()

Deletes one of the following field types from a model or component:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - Simple fields
        - Enumerable fields
        - Component fields
        - Component union fields
      </div>
      <div className="flex-1">
        - Relational fields
        - Union fields
        - Remote fields
        - Taxonomy fields
      </div>
    </div>


**Use cases:**
- Removing unused fields.
- Cleaning up deprecated fields.
- Restructuring content models.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all field data for all entries.
- May break conditional visibility dependencies.
- Cannot delete required fields (make optional first).

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteField({
  apiId: string,        // Required: The API ID of the field to delete
  parentApiId?: string, // Optional: API ID of parent model/component (use instead of modelApiId)
  modelApiId?: string   // Deprecated: Use parentApiId instead
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a simple field
client.deleteField({
  apiId: 'title',
  parentApiId: 'Post',
});

// Delete an enumerable field
client.deleteField({
  apiId: 'status',
  parentApiId: 'Post',
});

// Delete a component field
client.deleteField({
  apiId: 'seoMetadata',
  parentApiId: 'Post',
});

// Delete a component union field
client.deleteField({
  apiId: 'relatedPosts',
  parentApiId: 'Post',
});

// Delete a relational field
client.deleteField({
  apiId: 'author',
  parentApiId: 'Post',
});

// Delete a union field
client.deleteField({
  apiId: 'relatedPosts',
  parentApiId: 'Post',
});

// Delete a remote field
client.deleteField({
  apiId: 'externalData',
  parentApiId: 'Post',
});

// Delete a taxonomy field
client.deleteField({
  apiId: 'category',
  parentApiId: 'Post',
});

console.log('Field deleted');
```

  </TabsItem>
</Tabs>

## Enumerations

### createEnumeration()

Creates a new enumeration (enum) with its values.

**Use cases:**
- Creating status enums (`DRAFT`, `PUBLISHED`, `ARCHIVED`)
- Setting up category types (`NEWS`, `BLOG`, `TUTORIAL`)
- Defining content types (`ARTICLE`, `VIDEO`, `PODCAST`)
- Creating priority levels (`LOW`, `MEDIUM`, `HIGH`, `URGENT`)

**Important notes:**
- Enumeration `apiId` must be PascalCase.
- Enum values must be UPPER_SNAKE_CASE, such as, `DRAFT`, `PUBLISHED`.
- Enumeration `apiId` and `displayName` must be unique within environment.
- Enum values are referenced by their `apiId` in enumerable fields.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createEnumeration({
  apiId: string,                    // Required: Enumeration API ID
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  values: Array<{                   // Required: Array of enum values
    apiId: string,                  // Required: Value API ID
    displayName: string             // Required: Value display name
  }>,
  isSystem?: boolean               // Optional: System enumeration flag (only for AppTokens)
})
```
  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic enumeration with status values
client.createEnumeration({
  apiId: 'PostStatus',
  displayName: 'Post Status',
  description: 'Publication status for blog posts',
  values: [
    { apiId: 'DRAFT', displayName: 'Draft' },
    { apiId: 'REVIEW', displayName: 'In Review' },
    { apiId: 'PUBLISHED', displayName: 'Published' },
  ],
});

// Priority enumeration
client.createEnumeration({
  apiId: 'Priority',
  displayName: 'Priority',
  description: 'Task priority levels',
  values: [
    { apiId: 'LOW', displayName: 'Low' },
    { apiId: 'MEDIUM', displayName: 'Medium' },
    { apiId: 'HIGH', displayName: 'High' },
    { apiId: 'URGENT', displayName: 'Urgent' },
  ],
});
```

  </TabsItem>
</Tabs>


### updateEnumeration()

Updates an existing enumeration and its values.

**Use cases:**
- Adding new enum values.
- Updating enum value display names.
- Removing enum values.

**Important notes:**
- Enum values are managed via `valuesToAdd` and `valuesToRemove`.
- Cannot change enum `apiId` directly (use `newApiId`).
- Removing enum values may break existing entries using those values.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateEnumeration({
  apiId: string,                    // Required: Current enumeration API ID
  newApiId?: string,                // Optional: New API ID (to rename the enumeration)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  valuesToCreate?: Array<{          // Optional: New enum values to add
    apiId: string,                  // Required: Value API ID
    displayName: string             // Required: Value display name
  }>,
  valuesToUpdate?: Array<{          // Optional: Existing enum values to update
    apiId: string,                  // Required: Current value API ID
    newApiId?: string,              // Optional: New value API ID (to rename)
    displayName?: string            // Optional: New display name
  }>,
  valuesToDelete?: string[],        // Optional: Array of value API IDs to delete
  isSystem?: boolean               // Optional: System enumeration flag (only for AppTokens)
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Rename enumeration and update display name
client.updateEnumeration({
  apiId: 'PostStatus',
  newApiId: 'ArticleStatus',
  displayName: 'Article Status',
  description: 'Updated description',
});

// Add new enum values
client.updateEnumeration({
  apiId: 'PostStatus',
  valuesToCreate: [
    { apiId: 'ARCHIVED', displayName: 'Archived' },
    { apiId: 'SCHEDULED', displayName: 'Scheduled' },
  ],
});

// Update existing enum values
client.updateEnumeration({
  apiId: 'PostStatus',
  valuesToUpdate: [
    {
      apiId: 'REVIEW',
      newApiId: 'IN_REVIEW',
      displayName: 'In Review',
    },
  ],
});

// Delete enum values
client.updateEnumeration({
  apiId: 'PostStatus',
  valuesToDelete: ['ARCHIVED', 'SCHEDULED'],
});
```

  </TabsItem>
</Tabs>


### deleteEnumeration()

Deletes an enumeration.

**Use cases:**
- Removing unused enumerations.
- Cleaning up deprecated enums.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by enumerable fields.
- Must delete all enumerable fields using the enumeration first.

<Tabs>
  <TabsItem label="Parameter">

```ts
client.deleteEnumeration({
  apiId: string  // Required: The API ID of the enumeration to delete
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete an enumeration
client.deleteEnumeration({
  apiId: 'PostStatus',
});

console.log('Enumeration deleted');
```

  </TabsItem>
</Tabs>

### createEnumerableField()

Creates an enumerable field (enum field) on a model or component.

**Use cases:**
- Adding status fields to content models.
- Creating category/type selection fields.
- Setting up priority/rating fields.

**Important notes:**
- `enumerationApiId` must reference an existing enumeration.
- `initialValue` must be the enum value `apiId` (not `displayName`).
- Cannot use `isUnique` with `initialValue` or `migrationValue`.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createEnumerableField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model/component (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  enumerationApiId: string,         // Required: API ID of the enumeration to use
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized (default: false)
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique (default: false)
                                    // CANNOT be used with initialValue or migrationValue
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title (default: false)
  position?: number,               // Optional: Field position
  migrationValue?: string,          // Optional: Migration value for existing data (enum value API ID)
  initialValue?: string,            // Optional: Default value (enum value API ID, stringified)
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
  baseField: string,              // Required: API ID of the field that controls visibility
  operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
  enumerationValues?: string[],   // Required when baseField is enumeration type
  booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic enumerable field
client.createEnumerableField({
  parentApiId: 'Post',
  apiId: 'status',
  displayName: 'Status',
  enumerationApiId: 'PostStatus',
  isRequired: true,
  initialValue: 'DRAFT', // Enum value API ID
});

// Enumerable field with list support
client.createEnumerableField({
  parentApiId: 'Post',
  apiId: 'tags',
  displayName: 'Tags',
  enumerationApiId: 'PostTag',
  isList: true,
  isRequired: false,
});
```

  </TabsItem>
</Tabs>

**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateEnumerableField()

Updates an existing enumerable field.

**Use cases:**
- Changing enumeration reference
- Updating field visibility
- Adding conditional visibility

**Important notes:**
- Can change `enumerationApiId` to reference a different enumeration.
- Must ensure new enumeration has compatible values.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateEnumerableField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model/component API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique
                                    // CANNOT be used with initialValue or migrationValue
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title
  position?: number,                // Optional: Field position
  initialValue?: string,            // Optional: Default value (enum value API ID, stringified)
  migrationValue?: string,          // Optional: Migration value for existing data
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename field and change display name
client.updateEnumerableField({
  apiId: 'status',
  newApiId: 'publicationStatus',
  displayName: 'Publication Status',
  description: 'Current publication status',
});

// Update initial value
client.updateEnumerableField({
  apiId: 'status',
  initialValue: 'PUBLISHED', // Enum value API ID
});

// Update visibility
client.updateEnumerableField({
  apiId: 'status',
  visibility: VisibilityTypes.READ_ONLY,
});
```

  </TabsItem>
</Tabs>

**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Components

### createComponent()

Creates a new component.

**Use cases:**
- Creating reusable field groups (`SEO metadata`, `contact info`, `address`).
- Building modular content blocks (`CTA`, `image block`, `video block`).
- Setting up shared field structures across multiple models.

**Important notes:**
- Component `apiId` must be PascalCase.
- `apiId` and `apiIdPlural` must be different.
- Components can be nested (components can contain other components).
- Components cannot have required fields if used in multiple places.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createComponent({
  apiId: string,                    // Required: Component API ID
  apiIdPlural: string,              // Required: Plural API ID (used for lists)
  displayName: string,              // Required: Display name shown in the webapp
  description?: string              // Optional: Description of the component
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic component creation
client.createComponent({
  apiId: 'SeoMetadata',
  apiIdPlural: 'SeoMetadatas',
  displayName: 'SEO Metadata',
  description: 'Search engine optimization fields',
});

// Contact details component
client.createComponent({
  apiId: 'ContactDetails',
  apiIdPlural: 'ContactDetailsCollection',
  displayName: 'Contact Details',
  description: 'Phone and email contact information',
});
```

  </TabsItem>
</Tabs>

### updateComponent()

Updates an existing component.

**Use cases:**
- Renaming components.
- Updating descriptions.
- Managing component fields.

**Important notes:**
- Renaming updates all references to the component.
- Cannot change `apiId` directly (use `newApiId`).

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateComponent({
  apiId: string,                    // Required: Current component API ID
  newApiId?: string,                // Optional: New API ID (to rename the component)
  apiIdPlural?: string,             // Optional: New plural API ID
  displayName?: string,             // Optional: New display name
  description?: string              // Optional: New description
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename component and change display name
client.updateComponent({
  apiId: 'SeoMetadata',
  newApiId: 'SeoMeta',
  displayName: 'SEO Meta',
  description: 'Updated SEO metadata fields',
});

// Update only display name
client.updateComponent({
  apiId: 'ContactDetails',
  displayName: 'Contact Information',
});

// Update plural API ID
client.updateComponent({
  apiId: 'AuthorInfo',
  apiIdPlural: 'AuthorInfoCollection',
});
```

  </TabsItem>
</Tabs>

### deleteComponent()

Deletes a component.

**Use cases:**
- Removing unused components.
- Cleaning up deprecated components.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by any models or components.
- Must delete all component fields using the component first

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteComponent({
  apiId: string  // Required: The API ID of the component to delete
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a component
client.deleteComponent({
  apiId: 'SeoMetadata',
});

console.log('Component deleted');
```

  </TabsItem>
</Tabs>

### createComponentField()

Creates a component field that embeds a component into a model or another component.

**Use cases:**
- Embedding reusable components into models.
- Adding SEO metadata to content models.
- Including contact information components.

**Important notes:**
- `parentApiId` can be a model or another component (for nesting).
- `componentApiId` references the component to embed.
- `isList: true` allows multiple instances of the component.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createComponentField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model/component
  componentApiId: string,           // Required: API ID of the component to embed
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,         // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,               // Optional: Field position
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
})
```

    </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic component field - embed SEO component in Post model
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'seo',
  displayName: 'SEO',
  componentApiId: 'SeoMetadata',
  isRequired: false,
});

// Component field as a list
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  componentApiId: 'ImageBlock',
  isList: true,
  isRequired: false,
});

// Nested component - embed component inside another component
client.createComponentField({
  parentApiId: 'AuthorInfo', // Component API ID
  apiId: 'contact',
  displayName: 'Contact',
  componentApiId: 'ContactDetails', // Another component
  isRequired: false,
});

// Create basic component field
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'seo',
  displayName: 'SEO',
  description: 'Search engine optimization metadata',
  componentApiId: 'SeoMetadata',
});
```

  </TabsItem>
</Tabs>

**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateComponentField()

Updates an existing component field.

**Use cases:**
- Renaming component fields.
- Changing component reference
- Updating field visibility
- Adding conditional visibility.
- Changing required status.

**Important notes:**
- Can change `componentApiId` to reference a different component.
- Cannot change `isList` without potential data loss.
- When changing `isRequired` to `true`, must provide `migrationValue` for existing null entries.
- `visibilityCondition` can be set to `null` to remove it.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateComponentField({
  apiId: string,                    // Required: Current field API ID
  parentApiId: string,              // Required: Parent model/component API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  position?: number,                // Optional: Field position
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename field and change display name
client.updateComponentField({
  apiId: 'seo',
  parentApiId: 'Post',
  newApiId: 'seoMetadata',
  displayName: 'SEO Metadata',
  description: 'Search engine optimization fields',
});

// Update to make field required
client.updateComponentField({
  apiId: 'seo',
  parentApiId: 'Post',
  isRequired: true,
});

// Update visibility
client.updateComponentField({
  apiId: 'seo',
  parentApiId: 'Post',
  visibility: VisibilityTypes.READ_ONLY,
});
```

  </TabsItem>
</Tabs>

**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### createComponentUnionField()

Creates a modular component field that allows editors to choose from multiple component types.

**Use cases:**
- Building flexible page builders.
- Creating modular content systems.
- Allowing content editors to choose from multiple component types.

**Important notes:**
- `componentApiIds` must contain at least one component.
- Allows selecting from multiple component types in a single field.
- Useful for flexible, modular content structures.
- Content editors choose which component type to use per entry.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createComponentUnionField({
  // Required parameters
  apiId: string,                    // Field API ID (camelCase)
  parentApiId: string,              // API ID of parent model (PascalCase)
  displayName: string,              // Display name shown in UI
  componentApiIds: string[],        // Array of component API IDs (PascalCase) - at least one required

  // Optional parameters
  description?: string,             // Description text
  isVariantEnabled?: boolean,       // Enable variant support
  tableRenderer?: string,          // Table renderer identifier
  formRenderer?: string,           // Form renderer identifier
  tableExtension?: string,          // Table extension identifier
  formExtension?: string,           // Form extension identifier
  isList?: boolean,                 // Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Whether field is required (default: false)
  visibility?: VisibilityTypes,      // Visibility setting
  visibilityCondition?: {           // Conditional visibility
    baseField: string,              // API ID of the field that controls visibility
    operator: FieldConditionOperator, // Comparison operator
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Field position
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Complete example - creating components and union field
// 1. Create individual components
client.createComponent({
  apiId: 'CallToAction',
  apiIdPlural: 'CallToActions',
  displayName: 'Call to Action',
  description: 'CTA block with button',
});

client.createComponent({
  apiId: 'ImageBlock',
  apiIdPlural: 'ImageBlocks',
  displayName: 'Image Block',
  description: 'Image with caption',
});

client.createComponent({
  apiId: 'VideoBlock',
  apiIdPlural: 'VideoBlocks',
  displayName: 'Video Block',
  description: 'Video embed block',
});

// 2. Add fields to components
client.createSimpleField({
  parentApiId: 'CallToAction',
  type: SimpleFieldType.STRING,
  apiId: 'heading',
  displayName: 'Heading',
  isRequired: true,
});

client.createSimpleField({
  parentApiId: 'ImageBlock',
  type: SimpleFieldType.STRING,
  apiId: 'imageUrl',
  displayName: 'Image URL',
  isRequired: true,
});

// 3. Create the union field that allows any of these components
client.createComponentUnionField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  description: 'Flexible content blocks for rich posts',
  componentApiIds: ['CallToAction', 'ImageBlock', 'VideoBlock'],
  isList: true,
  isRequired: false,
});

// Landing page sections (conditional visibility)
client.createComponentUnionField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  componentApiIds: ['CallToAction', 'ImageBlock'],
  visibilityCondition: {
    baseField: 'status',
    operator: FieldConditionOperator.IS,
    enumerationValues: ['PUBLISHED'],
  },
});
```

  </TabsItem>
</Tabs>

**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateComponentUnionField()

Updates a modular component field.

**Use cases:**
- Adding new component types to union.
- Removing component types from union.
- Updating which components are available.

**Important notes:**
- `componentApiIds` replaces the entire list.
- To remove a component, provide complete list WITHOUT it.
- To add a component, provide complete list INCLUDING it.
- Cannot change `isList` or `isRequired` (not available in update)

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateComponentUnionField({
  // Required parameters
  apiId: string,                    // Current field API ID
  parentApiId: string,              // Parent model API ID

  // Optional parameters
  newApiId?: string,                // New API ID (to rename the field)
  displayName?: string,             // New display name
  description?: string,             // New description
  isVariantEnabled?: boolean,       // Enable/disable variant support
  componentApiIds?: string[],       // Array of component API IDs - REPLACES entire list
                                    // To remove a component, provide the complete list WITHOUT it
  visibilityCondition?: {           // Conditional visibility
    baseField: string,              // API ID of the field that controls visibility
    operator: FieldConditionOperator, // Comparison operator
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Field position
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts

// Basic update - rename field
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  newApiId: 'postContentBlocks',
  displayName: 'Post Content Blocks',
});

// Remove component from a component union field
client.updateComponentUnionField({
  apiId: '<api_id>',
  parentApiId: '<parent_api_id>',
  componentApiIds: [
    '<contributor_component_api_id>',
    // VideoBlock removed - only include components you want to keep
  ],
});

// Add a component to the union

// Original: ['CallToAction', 'ImageBlock'. Add VideoBlock - provide complete list INCLUDING VideoBlock
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  componentApiIds: [
    'CallToAction',
    'ImageBlock',
    'VideoBlock', // Added
  ],
});

// Update multiple properties
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  newApiId: 'sections',
  displayName: 'Page Sections',
  description: 'Flexible page sections',
  componentApiIds: ['HeroSection', 'FeaturesSection', 'TestimonialsSection'],
});

// Add conditional visibility
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  visibilityCondition: {
    baseField: 'status',
    operator: FieldConditionOperator.IS,
    enumerationValues: ['PUBLISHED'],
  },
});

// Remove conditional visibility
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  visibilityCondition: null, // Removes the visibility condition
});

// Modify component list

// Original union field with: ['CallToAction', 'ImageBlock', 'VideoBlock']

// Remove VideoBlock and add QuoteBlock
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  componentApiIds: [
    'CallToAction',
    'ImageBlock',
    'QuoteBlock', // Added
    // VideoBlock removed
  ],
});

```
</TabsItem>
</Tabs>


**Enums**
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Relational fields

### createRelationalField()

Creates a relational field that links models together (relation) or to assets (asset).

**Use cases:**
- Linking models together (`Post → Author`, `Product → Category`).
- Connecting content to assets (`Post → Featured Image`).
- Creating many-to-many relations (`Post ↔ Category`).
- Setting up one-to-many relations (`Author → Posts`).

**Important notes:**
- Cardinality is immutable. It is set at creation and cannot be changed later.
- `isRequired: true` is ONLY supported for ASSET type, not RELATION type.
- `reverseField.modelApiId` is the TARGET model being referenced.
- For unidirectional relations, `reverseField.position` should be negative.
- For components, `reverseField.isList` must be true to allow reconnection.

<Alert theme="info">

Relation cardinality is set at creation and **cannot be changed later**. You cannot convert:
- One-to-one → One-to-many
- One-to-many → Many-to-many
- Any other cardinality changes

If you need a different cardinality, you must delete and recreate the relation (which may cause data loss).

**For components and unidirectional relations:** The reverse side must have `isList: true` to allow reconnecting entries to the same component instance. Setting `isList: false` will prevent reconnection and may require recreating the relation.

</Alert>

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createRelationalField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  type: RelationalFieldType,        // Required: RELATION or ASSET
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether THIS side accepts multiple values (default: false)
                                    // Combined with reverseField.isList determines cardinality:
                                      // - false + reverse false = one-to-one (this is parent)
                                      // - false + reverse true = one-to-many (this is child)
                                      // - true + reverse false = many-to-one (this is parent)
                                      // - true + reverse true = many-to-many
                                    // CANNOT be changed after creation!
  isRequired?: boolean,             // Optional: Whether field is required
                                  // ONLY valid for ASSET type. Regular RELATION fields cannot be required
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  reverseField: {                   // Required: Configuration for the reverse side of the relation
    apiId: string,                  // Required: API ID for reverse field (appears on related model)
    modelApiId: string,             // Required: API ID of the related/target model
    displayName: string,            // Required: Display name for reverse field
    description?: string,           // Optional: Description for reverse field
    isList?: boolean,               // Optional: Whether reverse side accepts multiple values
                                    // IMPORTANT for components: Must be true to allow reconnection!
    isHidden?: boolean,             // Deprecated: Use visibility instead
    visibility?: VisibilityTypes,   // Optional: Visibility of reverse field
    isUnidirectional?: boolean,     // Optional: Create one-way relation (no reverse field shown in UI)
                                    // When true, related model won't display this relation
    position?: number               // Optional: Position of reverse field
                                    // MUST be negative for unidirectional relations
  },
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Optional: Reverse field position
                                    // MUST be negative for unidirectional relations
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Create a required uni-directional asset field
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'featuredImage',
  displayName: 'Featured Image',
  type: RelationalFieldType.ASSET,
  isRequired: true,
  reverseField: {
    isUnidirectional: true,
    apiId: 'featuredInPosts',
    displayName: 'Featured In Posts',
    modelApiId: 'Asset',
  },
});

// Create a many-to-many (M-N) relation
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'categories',
  displayName: 'Categories',
  type: RelationalFieldType.RELATION,
  isList: true,
  reverseField: {
    modelApiId: 'Category',
    apiId: 'posts',
    displayName: 'Posts',
    isList: true,
  },
});


// Basic relation - Post to Author (many-to-one)
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'author',
  displayName: 'Author',
  type: RelationalFieldType.RELATION,
  reverseField: {
    apiId: 'posts',
    modelApiId: 'Author',
    displayName: 'Posts',
    isList: true,
  },
});

// Asset relation - Post to featured image
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'featuredImage',
  displayName: 'Featured Image',
  type: RelationalFieldType.ASSET,
  isRequired: true, // isRequired is only supported for ASSET type
  reverseField: {
    apiId: 'featuredInPosts',
    modelApiId: 'Asset',
    displayName: 'Featured In Posts',
    isList: true,
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `RelationalFieldType`: `RELATION`, `ASSET`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateRelationalField()

Updates an existing relational field.

**Use cases:**
- Making relations unidirectional.
- Updating field visibility.
- Changing required status (for `ASSET` type only).

**Important notes:**
- Cannot change cardinality (`isList` cannot be changed).
- `isRequired` can only be changed for `ASSET` type.
- `isUnidirectional` is a top-level parameter (not in `reverseField`).
- No `reverseField` parameter in update (the reverse field is managed separately).

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateRelationalField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,               // Optional: New API ID (to rename the field)
  parentApiId?: string,            // Optional: Parent model API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,      // Optional: Enable/disable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (only for ASSET type!)
                                    // When changing to true, provide migrationValue for existing null entries
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isUnidirectional?: boolean,       // Optional: Make relation unidirectional
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Optional: Field position
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename field and change display name
client.updateRelationalField({
  apiId: 'author',
  parentApiId: 'Post',
  newApiId: 'postAuthor',
  displayName: 'Post Author',
  description: 'Author of the post',
});

// Update to make field required (only for ASSET type)
client.updateRelationalField({
  apiId: 'featuredImage',
  parentApiId: 'Post',
  isRequired: true, // Only works for ASSET type
});

// Make relation unidirectional
client.updateRelationalField({
  apiId: 'relatedPosts',
  parentApiId: 'Post',
  isUnidirectional: true,
});
```

  </TabsItem>
</Tabs>

**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Union fields

### createUnionField()

Creates a union field that links to multiple models (not components).

**Use cases:**
- Creating polymorphic relationships (`Post` can reference `Author` OR `Organization`).
- Allowing flexible model references.
- Building content that can link to multiple model types.

**Important notes:**
- `modelApiIds` must contain at least one model API ID.
- Allows selecting from multiple model types in a single field.
- `reverseField` is required and must specify `modelApiIds` array.
- Useful for polymorphic content relationships.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createUnionField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  reverseField: {                   // Required: Reverse field configuration
    apiId?: string,                 // Optional: Reverse field API ID
    modelApiIds: string[],          // Required: Complete array of model API IDs
                                  // NOTE: Replaces entire list (not merged with existing!)
                                  // Must include all models you want to keep
    displayName?: string,           // Optional: Reverse field display name
    description?: string,           // Optional: Reverse field description
    isList?: boolean,               // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
    isHidden?: boolean,             // Deprecated: Use visibility instead
    visibility?: VisibilityTypes,   // Optional: Reverse field visibility
    positions?: Array<{             // Optional: Position for each model
      modelApiId: string,           // Required: Model API ID
      position: number              // Required: Display osition
    }>
  },
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Optional: Field position
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic union field - link to multiple models
client.createUnionField({
  parentApiId: 'Post',
  apiId: 'authorOrEditor',
  displayName: 'Author or Editor',
  reverseField: {
    modelApiIds: ['Author', 'Editor'],
    displayName: 'Posts',
    isList: true,
  },
});

// Union field with list support
client.createUnionField({
  parentApiId: 'Post',
  apiId: 'relatedContent',
  displayName: 'Related Content',
  isList: true,
  reverseField: {
    modelApiIds: ['Post', 'Page', 'Video'],
    displayName: 'Related From',
    isList: true,
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateUnionField()

Updates an existing union field.

**Use cases:**
- Adding or removing model types from union.
- Updating reverse field configuration.

**Important notes:**
- `modelApiIds` replaces the entire list.
- `reverseField.modelApiIds` can be updated.
- Cannot change entire `reverseField` structure.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateUnionField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  position?: number,                 // Optional: Field position
  reverseField?: {                  // Optional: Update reverse field configuration
    modelApiIds: string[],          // Required: Array of model API IDs (complete list)
    positions?: Array<{             // Optional: Position for each model
      modelApiId: string,           // Required: Model API ID
      position: number              // Required: Position value
    }>
  },
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
})
```

  </TabsItem>
  <TabsItem label="Examples">


```ts
// Basic update - rename field and change display name
client.updateUnionField({
  apiId: 'authorOrEditor',
  parentApiId: 'Post',
  newApiId: 'contentAuthor',
  displayName: 'Content Author',
  description: 'Author or editor of the content',
});

// Update reverse field - change which models can be linked
client.updateUnionField({
  apiId: 'authorOrEditor',
  parentApiId: 'Post',
  reverseField: {
    modelApiIds: ['Author', 'Editor', 'Contributor'], // Complete list of models
  },
});

// Remove a model from the union (provide only models you want to keep)
client.updateUnionField({
  apiId: 'authorOrEditor',
  parentApiId: 'Post',
  reverseField: {
    modelApiIds: ['Author'], // Only Author remains, Editor is removed
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Remote sources

### createGraphQLRemoteSource()

Creates a new GraphQL remote source.

**Use cases:**
- Integrating external GraphQL APIs.
- Connecting to commerce platforms (CommerceTools, CommerceLayer)
- Building federated content systems.

**Important notes:**
- `prefix` is immutable. It cannot be changed after creation.
- `prefix` is prepended to all remote types.
- `introspectionUrl` can differ from `url` if introspection is on different endpoint.
- `remoteTypeDefinitions` allows custom GraphQL types.
- `OAuth` configuration is optional but required for protected APIs.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createGraphQLRemoteSource({
  displayName: string,              // Required: Display name
  prefix: string,                    // Required: Unique prefix for remote types (cannot be changed!)
  url: string,                       // Required: GraphQL endpoint URL
  kind: RemoteSourceKind,           // Required: Remote source kind enum
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod, // Required: HTTP method for introspection
  description?: string,              // Optional: Description
  headers?: JSON,                    // Optional: Custom headers (JSON object)
  introspectionUrl?: string,        // Optional: Separate URL for introspection (if different from url)
  introspectionHeaders?: JSON,      // Optional: Headers for introspection (JSON object)
  remoteTypeDefinitions?: {         // Optional: Custom GraphQL type definitions
    sdl: string                      // Required: GraphQL SDL string
  },
  debugEnabled?: boolean,          // Optional: Enable debug mode
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,                // Required: OAuth client ID
    clientSecret?: string,           // Optional: OAuth client secret
    scopes?: string[],               // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic GraphQL remote source
client.createGraphQLRemoteSource({
  displayName: 'External GraphQL API',
  prefix: 'External',
  url: 'https://api.example.com/graphql',
  kind: RemoteSourceKind.Custom,
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod.POST,
});

// GraphQL remote source with headers
client.createGraphQLRemoteSource({
  displayName: 'Protected GraphQL API',
  prefix: 'Protected',
  url: 'https://api.example.com/graphql',
  kind: RemoteSourceKind.Custom,
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod.POST,
  headers: {
    Authorization: 'Bearer api-token',
    'X-API-Key': 'your-api-key',
  },
});

// GraphQL remote source with OAuth
client.createGraphQLRemoteSource({
  displayName: 'OAuth GraphQL API',
  prefix: 'OAuth',
  url: 'https://api.example.com/graphql',
  kind: RemoteSourceKind.Custom,
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod.POST,
  oAuth: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scopes: ['read:products', 'write:products'],
    authorizationGrantType: OAuthGrantType.client_credentials,
    authorizationUrl: 'https://auth.example.com/oauth/token',
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `GraphQLRemoteSourceIntrospectionMethod`: `GET`, `POST`
- `OAuthGrantType`: `client_credentials`

### updateGraphQLRemoteSource()

Updates an existing GraphQL remote source.

**Use cases:**
- Updating remote source URLs.
- Changing authentication headers.
- Modifying OAuth configuration.
- Adding/updating remote type definitions.
- Updating introspection settings.

**Important notes:**
- `prefix` cannot be changed (immutable).
- `remoteTypeDefinitionsToUpsert` uses create/update/delete structure.
- OAuth configuration can be updated.
- `introspectionUrl` and `introspectionMethod` can be changed.
- Headers can be updated for authentication.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateGraphQLRemoteSource({
  prefix: string,                   // Required: Remote source prefix (used to identify the source)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  url?: string,                     // Optional: New GraphQL endpoint URL
  headers?: JSON,                   // Optional: Custom headers (JSON object)
  introspectionUrl?: string,       // Optional: Separate URL for introspection
  introspectionMethod?: GraphQLRemoteSourceIntrospectionMethod, // Optional: HTTP method for introspection
  introspectionHeaders?: JSON,     // Optional: Headers for introspection (JSON object)
  remoteTypeDefinitionsToUpsert?: { // Optional: Manage remote type definitions
    remoteTypeDefinitionsToCreate?: Array<{ // Optional: Create new type definitions
      sdl: string                    // Required: GraphQL SDL string
    }>,
    remoteTypeDefinitionsToUpdate?: Array<{ // Optional: Update existing type definitions
      apiId: string,                 // Required: Type definition API ID
      sdl?: string                   // Optional: New SDL string
    }>,
    remoteTypeDefinitionsToDelete?: Array<{ // Optional: Delete type definitions
      apiId: string                  // Required: Type definition API ID
    }>
  },
  debugEnabled?: boolean,          // Optional: Enable/disable debug mode
  kind?: RemoteSourceKind,         // Optional: Remote source kind enum
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,               // Required: OAuth client ID
    clientSecret?: string,          // Optional: OAuth client secret
    scopes?: string[],              // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - change display name and URL
client.updateGraphQLRemoteSource({
  prefix: 'External',
  displayName: 'Updated GraphQL API',
  url: 'https://api.example.com/new-graphql',
});

// Update headers
client.updateGraphQLRemoteSource({
  prefix: 'External',
  headers: {
    Authorization: 'Bearer new-token',
    'X-API-Key': 'new-api-key',
  },
});

// Add new remote type definitions
client.updateGraphQLRemoteSource({
  prefix: 'External',
  remoteTypeDefinitionsToUpsert: {
    remoteTypeDefinitionsToCreate: [
      {
        sdl: `
          input NewFilterInput {
            field: String!
            value: String!
          }
        `,
      },
    ],
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `GraphQLRemoteSourceIntrospectionMethod`: `GET`, `POST`
- `OAuthGrantType`: `client_credentials`

### refreshGraphQLRemoteSourceSchema()

Refreshes the schema for a GraphQL remote source.

**Use cases:**
- Updating remote schema after API changes.
- Syncing with latest remote API schema.
- Refreshing available types and fields.

**Important notes:**
- Only requires prefix to identify the remote source.
- Async operation. It may take time to complete.
- Updates available types and fields from remote schema.
- Should be called when remote API schema changes.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.refreshGraphQLRemoteSourceSchema({
  prefix: string  // Required: Remote source prefix
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Refresh schema for a GraphQL remote source
client.refreshGraphQLRemoteSourceSchema({
  prefix: 'External',
});

// Refresh schema after updating the remote API
client.refreshGraphQLRemoteSourceSchema({
  prefix: 'CommerceTools',
});
```

</TabsItem>
</Tabs>

### createRESTRemoteSource()

Creates a new REST remote source.

**Use cases:**
- Integrating REST APIs.
- Connecting to external REST services.
- Building API integrations.

**Important notes:**
- `prefix` is immutable. It cannot be changed after creation.
- `remoteTypeDefinitions` define available types and operations.
- `OAuth` configuration is optional but required for protected APIs.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createRESTRemoteSource({
  displayName: string,              // Required: Display name
  prefix: string,                   // Required: Unique prefix for remote types (cannot be changed!)
  url: string,                      // Required: REST API base URL
  kind: RemoteSourceKind,           // Required: Remote source kind enum
  description?: string,              // Optional: Description
  headers?: JSON,                    // Optional: Custom headers (JSON object)
  remoteTypeDefinitions?: {         // Optional: Remote type definitions
    sdl: string                      // Required: GraphQL SDL string defining types
  },
  debugEnabled?: boolean,           // Optional: Enable debug mode
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,               // Required: OAuth client ID
    clientSecret?: string,          // Optional: OAuth client secret
    scopes?: string[],              // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic REST remote source
client.createRESTRemoteSource({
  displayName: 'External REST API',
  prefix: 'External',
  url: 'https://api.example.com',
  kind: RemoteSourceKind.Custom,
});

// REST remote source with headers
client.createRESTRemoteSource({
  displayName: 'Protected REST API',
  prefix: 'Protected',
  url: 'https://api.example.com',
  kind: RemoteSourceKind.Custom,
  headers: {
    Authorization: 'Bearer api-token',
    'X-API-Key': 'your-api-key',
  },
});

// REST remote source with OAuth
client.createRESTRemoteSource({
  displayName: 'OAuth REST API',
  prefix: 'OAuth',
  url: 'https://api.example.com',
  kind: RemoteSourceKind.Custom,
  oAuth: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scopes: ['read:products', 'write:products'],
    authorizationGrantType: OAuthGrantType.client_credentials,
    authorizationUrl: 'https://auth.example.com/oauth/token',
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `OAuthGrantType`: `client_credentials`

### updateRESTRemoteSource()

Updates an existing REST remote source.

**Use cases:**
- Updating REST API URLs.
- Modifying OAuth configuration.
- Adding/updating remote type definitions.
- Changing authentication settings.

**Important notes:**
- `prefix` cannot be changed (immutable).
- `remoteTypeDefinitionsToUpsert` uses create/update/delete structure.
- OAuth configuration can be updated.
- URL can be changed if API endpoint changes.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateRESTRemoteSource({
  prefix: string,                   // Required: Remote source prefix (used to identify the source)
  displayName: string,              // Required: New display name
  description?: string,             // Optional: New description
  url?: string,                     // Optional: New REST API base URL
  headers?: JSON,                   // Optional: Custom headers (JSON object)
  remoteTypeDefinitionsToUpsert?: { // Optional: Manage remote type definitions
    remoteTypeDefinitionsToCreate?: Array<{ // Optional: Create new type definitions
      sdl: string                    // Required: GraphQL SDL string
    }>,
    remoteTypeDefinitionsToUpdate?: Array<{ // Optional: Update existing type definitions
      apiId: string,                 // Required: Type definition API ID
      sdl?: string                   // Optional: New SDL string
    }>,
    remoteTypeDefinitionsToDelete?: Array<{ // Optional: Delete type definitions
      apiId: string                  // Required: Type definition API ID
    }>
  },
  debugEnabled?: boolean,          // Optional: Enable/disable debug mode
  kind?: RemoteSourceKind,         // Optional: Remote source kind enum
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,               // Required: OAuth client ID
    clientSecret?: string,          // Optional: OAuth client secret
    scopes?: string[],              // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - change display name and URL
client.updateRESTRemoteSource({
  prefix: 'External',
  displayName: 'Updated REST API',
  url: 'https://api.example.com/new-endpoint',
});

// Update headers
client.updateRESTRemoteSource({
  prefix: 'External',
  displayName: 'External REST API',
  headers: {
    Authorization: 'Bearer new-token',
    'X-API-Key': 'new-api-key',
  },
});

// Add new remote type definitions
client.updateRESTRemoteSource({
  prefix: 'External',
  displayName: 'External REST API',
  remoteTypeDefinitionsToUpsert: {
    remoteTypeDefinitionsToCreate: [
      {
        sdl: `
          type Product {
            id: ID!
            name: String!
            price: Float!
          }
        `,
      },
    ],
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `OAuthGrantType`: `client_credentials`

### deleteRemoteSource()

Deletes a remote source.

**Use cases:**
- Removing unused remote sources.
- Cleaning up deprecated API integrations.
- Restructuring remote integrations.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by remote fields.
- Must delete all remote fields using the remote source first.
- Deletes all remote type definitions.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteRemoteSource({
  prefix: string  // Required: The prefix of the remote source to delete
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a remote source
client.deleteRemoteSource({
  prefix: 'External',
});

console.log('Remote source deleted');
```

  </TabsItem>
</Tabs>

## Remote fields

### createRemoteField()

Creates a remote field that fetches data from a GraphQL or REST remote source.

**Use cases:**
- Fetching data from external APIs.
- Displaying remote content in Hygraph.
- Building hybrid content systems.

**Important notes:**
- Requires existing remote source (remoteSourceApiId).
- `remoteConfig` defines how to fetch data.
- `inputArgs` allow passing parameters to remote API.
- Field type determined by remote source type (GRAPHQL or REST).

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createRemoteField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model
  type: RemoteFieldType,            // Required: GRAPHQL or REST
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,                // Optional: Field position
  remoteConfig: {                   // Required: Configuration for fetching remote data
    returnTypeApiId: string,       // Required: API ID of return type defined in remote source
                                    // Must exist in the remote source's type definitions
    remoteSourcePrefix: string,    // Required: Prefix of the remote source to use
                                    // Must match prefix from createGraphQLRemoteSource or createRESTRemoteSource
    method: RemoteFieldApiMethod,   // Required: HTTP method (GET or POST)
                                    // GET for simple queries, POST for mutations or complex queries
    headers?: JSON,                 // Optional: Custom HTTP headers (JSON object)
                                    // Example: { "Authorization": "Bearer token" }
    cacheTTLSeconds?: number,       // Optional: Cache duration in seconds
                                    // 0 = no cache, default varies by remote source type
    graphQLQuery?: string,          // Required for GRAPHQL type remote fields
                                    // Complete GraphQL query string
    restPath?: string,             // Required for REST type remote fields
                                    // API endpoint path (e.g., "/users/{id}")
                                    // Can include path parameters in curly braces
    forwardClientHeaders?: boolean // Optional: Pass client request headers to remote API (default: false)
                                    // Useful for authentication/authorization
  },
  inputArgs?: Array<{              // Optional: Arguments passed to remote field query
    remoteTypeApiId: string,       // Required: API ID of input type from remote source
    apiId: string,                 // Required: Argument name (used in GraphQL query or REST path)
    isRequired: boolean,            // Required: Whether this argument must be provided
    isList: boolean                // Required: Whether argument accepts array of values
  }>
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// GraphQL remote field
client.createRemoteField({
  parentApiId: 'Product',
  apiId: 'externalData',
  displayName: 'External Data',
  type: RemoteFieldType.GRAPHQL,
  remoteConfig: {
    returnTypeApiId: 'ExternalProduct',
    remoteSourcePrefix: 'External',
    method: RemoteFieldApiMethod.POST,
    graphQLQuery: `
      query GetProduct($id: ID!) {
        product(id: $id) {
          id
          name
          price
        }
      }
    `,
    headers: {
      Authorization: 'Bearer token',
    },
    cacheTTLSeconds: 300,
  },
});

// REST remote field
client.createRemoteField({
  parentApiId: 'Product',
  apiId: 'externalInventory',
  displayName: 'External Inventory',
  type: RemoteFieldType.REST,
  remoteConfig: {
    returnTypeApiId: 'Inventory',
    remoteSourcePrefix: 'External',
    method: RemoteFieldApiMethod.GET,
    restPath: '/inventory/{id}',
    headers: {
      'X-API-Key': 'api-key',
    },
    forwardClientHeaders: true,
    cacheTTLSeconds: 60,
  },
});
```

  </TabsItem>
</Tabs>

**Enum**

- `RemoteFieldType`: `GRAPHQL`, `REST`
- `RemoteFieldApiMethod`: `GET`, `POST`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`

### updateRemoteField()

This example shows how to update an existing remote field.

**Use cases:**
- Updating remote field configuration.
- Changing API endpoints or methods.
- Modifying input arguments.

**Important notes:**
- `remoteConfig` can be updated.
- `inputArgs` can be modified.
- Field type cannot be changed.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateRemoteField({
  apiId: string,                    // Required: Current field API ID
  parentApiId: string,              // Required: Parent model API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  extensions?: JSON,                // Optional: Extensions JSON
  meta?: JSON,                      // Optional: Meta JSON
  position?: number,                // Optional: Field position
  remoteConfig?: {                  // Optional: Update remote field configuration
    returnTypeApiId?: string,       // Optional: New return type API ID
    remoteSourcePrefix?: string,    // Optional: New remote source prefix
    method?: RemoteFieldApiMethod,  // Optional: HTTP method
    headers?: JSON,                 // Optional: Custom headers
    cacheTTLSeconds?: number,       // Optional: Cache TTL in seconds
    graphQLQuery?: string,          // Optional: GraphQL query (for GRAPHQL type)
    restPath?: string,             // Optional: REST path (for REST type)
    forwardClientHeaders?: boolean // Optional: Forward client headers
  },
  inputArgs?: {                    // Optional: Update input arguments (add/remove/update structure)
    fieldInputArgsToCreate?: Array<{ // Optional: Create new input arguments
      remoteTypeApiId: string,     // Required: API ID of the remote input type
      apiId: string,                // Required: Argument API ID
      isRequired: boolean,           // Required: Whether argument is required
                                    // When changing to true, provide migrationValue for existing null entries
      isList: boolean               // Required: Whether argument is a list
    }>,
    fieldInputArgsToUpdate?: Array<{ // Optional: Update existing input arguments
      argApiId: string,             // Required: Current argument API ID
      remoteTypeApiId?: string,     // Optional: New remote type API ID
      apiId?: string,               // Optional: New argument API ID
      isRequired?: boolean,          // Optional: Whether argument is required
                                    // When changing to true, provide migrationValue for existing null entries
      isList?: boolean              // Optional: Whether argument is a list
    }>,
    fieldInputArgsToDelete?: Array<{ // Optional: Delete input arguments
      argApiId: string              // Required: Argument API ID to delete
    }>
  }
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename field and change display name
client.updateRemoteField({
  apiId: 'externalData',
  parentApiId: 'Product',
  newApiId: 'externalProductData',
  displayName: 'External Product Data',
});

// Update remote config - change GraphQL query
client.updateRemoteField({
  apiId: 'externalData',
  parentApiId: 'Product',
  remoteConfig: {
    graphQLQuery: `
      query GetProduct($id: ID!) {
        product(id: $id) {
          id
          name
          price
          description
        }
      }
    `,
    cacheTTLSeconds: 600,
  },
});

// Add new input arguments
client.updateRemoteField({
  apiId: 'externalData',
  parentApiId: 'Product',
  inputArgs: {
    fieldInputArgsToCreate: [
      {
        remoteTypeApiId: 'Boolean',
        apiId: 'includeReviews',
        isRequired: false,
        isList: false,
      },
    ],
  },
});
```

  </TabsItem>
</Tabs>

**Enum**
- `RemoteFieldType`: `GRAPHQL`, `REST`
- `RemoteFieldApiMethod`: `GET`, `POST`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`

## Locales

### createLocale()

Creates a new locale (language/region) for content localization.

**Use cases:**
- Setting up multi-language content
- Adding new language support
- Configuring localization

**Important notes:**
- Locale code must follow ISO 639-1 format, such as `en`, `de`, `fr`.
- `isDefault` determines default locale
- Only one locale can be default
- Locales are environment-specific

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createLocale({
  apiId: string,                    // Required: Locale API ID (e.g., "en", "en_US", "de")
  displayName: string,              // Required: Display name (e.g., "English", "English (US)", "German")
  description?: string              // Optional: Description
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic locale creation
client.createLocale({
  apiId: 'en',
  displayName: 'English',
  description: 'English language',
});

// Locale with region
client.createLocale({
  apiId: 'en_US',
  displayName: 'English (US)',
  description: 'English - United States',
});

// Multiple locales
client.createLocale({
  apiId: 'de',
  displayName: 'German',
  description: 'German language',
});

client.createLocale({
  apiId: 'fr',
  displayName: 'French',
  description: 'French language',
});
```

  </TabsItem>
</Tabs>

### updateLocale()

Updates an existing locale.

**Use cases:**
- Changing default locale.
- Updating locale display names.
- Modifying locale settings.

**Important notes:**
- Changing `isDefault` to `true` sets this as default and removes default from others.
- Locale `apiId` cannot be changed.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateLocale({
  apiId: string,                    // Required: Current locale API ID
  newApiId?: string,                // Optional: New API ID (to rename the locale)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isDefault?: boolean               // Optional: Whether this locale is the default
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename locale and change display name
client.updateLocale({
  apiId: 'en',
  newApiId: 'en_US',
  displayName: 'English (US)',
  description: 'English - United States',
});

// Set locale as default
client.updateLocale({
  apiId: 'en',
  isDefault: true,
});

// Update only display name
client.updateLocale({
  apiId: 'de',
  displayName: 'Deutsch',
});
```

  </TabsItem>
</Tabs>

### deleteLocale()

Deletes a locale.

**Use cases:**

- Removing language support.
- Cleaning up unused locales.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete default locale.
- May affect localized content.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteLocale({
  apiId: string,                    // Required: The API ID of the locale to delete
  force?: boolean                   // Optional: Force delete even if locale has content
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Delete a locale
client.deleteLocale({
  apiId: 'de',
});

// Force delete a locale (even if it has content)
client.deleteLocale({
  apiId: 'fr',
  force: true,
});

console.log('Locale deleted');
```

  </TabsItem>
</Tabs>

## Stages

### createStage()

Creates a new content stage, such as `Draft`, `Published`, `Archived`.

**Use cases:**

- Setting up content publishing stages (`Draft`, `Published`, `Archived`).
- Creating content lifecycle stages.
- Building stage-based content workflows.

**Important notes:**
- Stage `apiId` typically `UPPERCASE`, such as, `DRAFT`, `PUBLISHED`.
- `color` uses `ColorPalette` enum.
- Stages are environment-specific.
- `position` determines display order.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createStage({
  apiId: string,                    // Required: Stage API ID (e.g., "DRAFT", "PUBLISHED", "ARCHIVED")
  displayName: string,              // Required: Display name (e.g., "Draft", "Published", "Archived")
  color: ColorPalette,              // Required: Stage color enum
  description?: string,             // Optional: Description
  position?: number                 // Optional: Stage position (for ordering)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic stage creation
client.createStage({
  apiId: 'DRAFT',
  displayName: 'Draft',
  color: ColorPalette.BLUE,
  description: 'Work in progress',
});

// Published stage
client.createStage({
  apiId: 'PUBLISHED',
  displayName: 'Published',
  color: ColorPalette.GREEN,
  description: 'Published content',
});

// Stage with position
client.createStage({
  apiId: 'REVIEW',
  displayName: 'In Review',
  color: ColorPalette.YELLOW,
  description: 'Awaiting review',
  position: 1,
});
```

  </TabsItem>
</Tabs>

**Enum**

- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### updateStage()

Updates an existing content stage.

**Use cases:**
- Renaming stages.
- Changing stage colors.
- Updating stage descriptions.
- Reordering stages.

**Important notes:**
- Uses `display` (not `displayName`) for display name.
- Can change color for visual distinction.
- `position` controls ordering.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateStage({
  apiId: string,                    // Required: Current stage API ID
  newApiId?: string,                // Optional: New API ID (to rename the stage)
  display?: string,                 // Optional: New display name
  description?: string,             // Optional: New description
  color?: ColorPalette,            // Optional: New stage color enum
  position?: number                 // Optional: New stage position
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename stage and change display name
client.updateStage({
  apiId: 'DRAFT',
  newApiId: 'DRAFT_STAGE',
  display: 'Draft Stage',
  description: 'Work in progress',
});

// Update color
client.updateStage({
  apiId: 'DRAFT',
  color: ColorPalette.BLUE,
});

// Update display name
client.updateStage({
  apiId: 'PUBLISHED',
  display: 'Published Content',
});

// Update position
client.updateStage({
  apiId: 'REVIEW',
  position: 1,
});
```

  </TabsItem>
</Tabs>

**Enum**

- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### deleteStage()

Deletes a content stage.

**Use cases:**
- Removing unused stages.
- Cleaning up test stages.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by entries.
- May affect published content.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteStage({
  apiId: string,                    // Required: The API ID of the stage to delete
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a stage
client.deleteStage({
  apiId: 'ARCHIVED',
});

console.log('Stage deleted');
```

  </TabsItem>
</Tabs>

## Taxonomies

Taxonomies organize content into hierarchical categories.

### createTaxonomy()

Creates a taxonomy with hierarchical nodes.

**Use cases:**
- Creating hierarchical category systems.
- Building tag hierarchies.
- Setting up nested classification systems.

**Important notes:**
- Can create with either `rootNode` OR `taxonomyNodes`.
- `rootNode` approach: provides root node, children become taxonomy nodes.
- `taxonomyNodes` approach: provides all nodes, root has parent: null.
- Taxonomy `apiId` must be PascalCase and unique.

<Tabs>
  <TabsItem label="Parameters">

```ts
// Approach 1: Hierarchical structure (easier to read)
client.createTaxonomy({
  apiId: string,                    // Required: Taxonomy API ID
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  rootNode?: {                      // Optional: Root node with children (mutually exclusive with taxonomyNodes)
    apiId: string,                  // Required: Root node API ID
    displayName: string,            // Required: Root node display name
    children?: Array<{              // Optional: Child nodes (recursive structure)
      apiId: string,                // Required: Child node API ID
      displayName: string,           // Required: Child node display name
      children?: Array<...>         // Optional: Nested children (recursive)
    }>
  },
})

// Approach 2: Flat array (easier for programmatic generation)

client.createTaxonomy({
  apiId: string,                    // Required: Taxonomy API ID
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  taxonomyNodes?: Array<{          // Optional: Flat array of nodes (mutually exclusive with rootNode)
    apiId: string,                  // Required: Node API ID
    displayName: string,           // Required: Node display name
    parent?: string                 // Optional: Parent node API ID (null for root node)
  }>
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Basic taxonomy with rootNode (nested structure)
client.createTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Blog Categories',
  description: 'Hierarchical blog categorization',
  rootNode: {
    apiId: 'technology',
    displayName: 'Technology',
    children: [
      {
        apiId: 'webDev',
        displayName: 'Web Development',
        children: [
          { apiId: 'react', displayName: 'React' },
          { apiId: 'vue', displayName: 'Vue.js' },
        ],
      },
    ],
  },
});

// Taxonomy with flat taxonomyNodes array
client.createTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Blog Categories',
  taxonomyNodes: [
    { apiId: 'technology', displayName: 'Technology', parent: null },
    { apiId: 'webDev', displayName: 'Web Development', parent: 'technology' },
  ],
});
```

  </TabsItem>
</Tabs>

### updateTaxonomy()

Updates metadata of an existing taxonomy. Nodes are managed separately.

**Use cases:**
- Renaming taxonomies.
- Updating taxonomy descriptions.
- Changing taxonomy display names.

**Important notes:**
- Can change `displayName` and `description`.
- Cannot change `apiId` directly (use `newApiId`).
- Renaming updates all references to the taxonomy.

<Tabs>
  <TabsItem label="Parameters">

```ts
// Update a taxonomy
client.updateTaxonomy({
  apiId: string,                    // Required: Current taxonomy API ID
  newApiId?: string,                // Optional: New API ID (to rename the taxonomy)
  displayName?: string,             // Optional: New display name
  description?: string              // Optional: New description
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
  // Basic update - rename taxonomy and change display name
client.updateTaxonomy({
  apiId: 'BlogCategories',
  newApiId: 'ArticleCategories',
  displayName: 'Article Categories',
  description: 'Updated categorization system',
});

// Update only display name
client.updateTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Content Categories',
});
```

  </TabsItem>
</Tabs>

### deleteTaxonomy()

Deletes a taxonomy and all its nodes. You cannot delete a taxonomy if any fields reference it.

**Use cases:**
- Removing unused taxonomies.
- Cleaning up deprecated category systems.
- Restructuring classification systems.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all taxonomy nodes.
- Cannot delete if used by taxonomy fields.
- Must delete all taxonomy fields using the taxonomy first.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteTaxonomy({
  apiId: string  // Required: The API ID of the taxonomy to delete
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a taxonomy
client.deleteTaxonomy({
  apiId: 'BlogCategories',
});

console.log('Taxonomy deleted');
```

  </TabsItem>
</Tabs>

### createTaxonomyNode()

Adds a new node to an existing taxonomy.

**Use cases:**
- Adding categories to existing taxonomies.
- Building nested category structures.
- Expanding taxonomy hierarchies.

**Important notes:**
- `parentApiId: null` creates a root-level node.
- `parentApiId` references another taxonomy node's apiId.
- Nodes can be nested to any depth.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createTaxonomyNode({
  taxonomyApiId: string,            // Required: API ID of the taxonomy
  apiId: string,                    // Required: Node API ID
  displayName: string,              // Required: Node display name
  parent?: string,                  // Optional: Parent node API ID (null or omit for root node)
  children?: Array<{                // Optional: Child nodes (nested structure)
    apiId: string,                  // Required: Child node API ID
    displayName: string,            // Required: Child node display name
    children?: Array<...>           // Optional: Nested children (recursive)
  }>
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Create a root node (no parent)
client.createTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'technology',
  displayName: 'Technology',
});

// Create a child node
client.createTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'webDev',
  displayName: 'Web Development',
  parent: 'technology', // Parent node API ID
});

// Create a node with nested children
client.createTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'technology',
  displayName: 'Technology',
  parent: null, // Root node
  children: [
    {
      apiId: 'webDev',
      displayName: 'Web Development',
      children: [
        { apiId: 'react', displayName: 'React' },
        { apiId: 'vue', displayName: 'Vue.js' },
      ],
    },
  ],
});
```

  </TabsItem>
</Tabs>

### updateTaxonomyNode()

Updates an existing taxonomy node.

**Use cases:**
- Moving taxonomy nodes (changing parent).
- Renaming taxonomy nodes.
- Updating node descriptions.
- Reorganizing taxonomy hierarchy.

**Important notes:**
- `parent` parameter changes the node's parent (can move nodes).
- Set `parent: null` to make a node root-level.
- Can change `apiId` using `newApiId`.
- Moving nodes updates the entire hierarchy.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateTaxonomyNode({
  taxonomyApiId: string,            // Required: API ID of the taxonomy
  apiId: string,                    // Required: Current node API ID
  newApiId?: string,                // Optional: New API ID (to rename the node)
  displayName?: string,             // Optional: New display name
  parent?: string | null            // Optional: New parent node API ID (null for root node)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename node and change display name
client.updateTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'webDev',
  newApiId: 'webDevelopment',
  displayName: 'Web Development',
});

// Move node to different parent
client.updateTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'react',
  parent: 'frontend', // Move 'react' under 'frontend' node
});

// Move node to root (make it a root node)
client.updateTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'technology',
  parent: null, // Make it a root node
});
```

  </TabsItem>
</Tabs>

### deleteTaxonomyNode()

Deletes a taxonomy node and all its children.

**Use cases:**
- Removing unused taxonomy nodes.
- Cleaning up deprecated categories.
- Simplifying taxonomy hierarchies.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes the node and all its children (cascading deletion).
- Cannot delete if used by taxonomy fields.
- Must update or delete taxonomy fields using the node first.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteTaxonomyNode({
  taxonomyApiId: string,            // Required: API ID of the taxonomy
  apiId: string                      // Required: API ID of the node to delete
})
```

</TabsItem>
  <TabsItem label="Example">

```ts
// Delete a taxonomy node
client.deleteTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'webDev',
});

console.log('Taxonomy node deleted');
```

  </TabsItem>
</Tabs>

### createTaxonomyField()

Creates a taxonomy field that links a model to a taxonomy.

**Use cases:**
- Linking models to taxonomies.
- Adding category/tag fields to content.
- Creating classification systems.

**Important notes:**
- `initialValue` and `migrationValue` must be JSON stringified.
- Single value: `JSON.stringify('nodeApiId')`.
- List value: `JSON.stringify(['node1', 'node2'])`.
- Cannot use `isUnique` with `initialValue` or `migrationValue`.
- `migrationValue` is used for existing data, `initialValue` for new entries.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createTaxonomyField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model
  taxonomyApiId: string,            // Required: API ID of the taxonomy to link to
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique (default: false)
                                    // CANNOT be used with initialValue or migrationValue
  initialValue?: string,            // Optional: JSON stringified initial value (for new entries)
                                    // If isList is true, this should be a JSON stringified array of apiIds
                                    // If isList is false, this should be a JSON stringified apiId
  migrationValue?: string,          // Optional: JSON stringified taxonomy node API ID for initial value
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,                // Optional: Field position
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic taxonomy field - single selection
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'category',
  displayName: 'Category',
  taxonomyApiId: 'BlogCategories',
  isRequired: false,
});

// Taxonomy field with list support (multiple selections)
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'categories',
  displayName: 'Categories',
  taxonomyApiId: 'BlogCategories',
  isList: true,
  isRequired: false,
});

// Taxonomy field with initial value
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'category',
  displayName: 'Category',
  taxonomyApiId: 'BlogCategories',
  initialValue: JSON.stringify('technology'), // JSON stringified taxonomy node API ID
});
```

  </TabsItem>
</Tabs>

**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateTaxonomyField()

Updates an existing taxonomy field.

**Use cases:**
- Renaming taxonomy fields.
- Updating field visibility.
- Changing required/unique status.
- Updating initial/migration values.
- Adding conditional visibility.
- Changing taxonomy reference.

**Important notes:**
- `initialValue` and `migrationValue` must be JSON stringified.
- Single value: `JSON.stringify('nodeApiId')`.
- List value: `JSON.stringify(['node1', 'node2'])`.
- Cannot use `isUnique` with `initialValue` or `migrationValue`.
- When changing `isRequired` to `true`, provide `migrationValue` for existing null entries.
- Cannot change `isList` without potential data loss.
- `visibilityCondition` can be set to `null` to remove it.
- Cannot change `taxonomyApiId`. Taxonomy reference is immutable.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateTaxonomyField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique
                                    // CANNOT be used with initialValue or migrationValue
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,                // Optional: Field position
  initialValue?: string,            // Optional: JSON stringified initial value (for new entries)
  migrationValue?: string,          // Optional: JSON stringified taxonomy node API ID (for existing data)
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename field and change display name
client.updateTaxonomyField({
  apiId: 'category',
  parentApiId: 'Post',
  newApiId: 'primaryCategory',
  displayName: 'Primary Category',
});

// Update initial value
client.updateTaxonomyField({
  apiId: 'category',
  parentApiId: 'Post',
  initialValue: JSON.stringify('technology'), // Single value
});

// Update initial value for list field
client.updateTaxonomyField({
  apiId: 'categories',
  parentApiId: 'Post',
  initialValue: JSON.stringify(['technology', 'business']), // Array
});
```

  </TabsItem>
</Tabs>

**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Workflows

### createWorkflow()

**Use cases:**
- Setting up content approval processes.
- Creating editorial workflows.
- Building multi-step content review systems.

**Important notes:**
- Steps are created in the order provided unless position is specified. If a position conflicts, the new step is inserted at the next available position.
- First step cannot have `returnToStep`.
- `roleOverrides` at workflow level bypasses all steps.
- `allowedRoles` at step level controls who can work at that step.
- `publishStages` determines which stages can be published from a step.
- Steps with conflicting positions are inserted at next available slot.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createWorkflow({
  apiId: string,                    // Required: Workflow API ID
  displayName: string,             // Required: Display name
  description?: string,             // Optional: Description
  enabled: boolean,                 // Required: Whether workflow is enabled
  modelApiIds?: string[],          // Optional: Array of model API IDs to apply workflow to
roleOverrides?: string[],        // Optional: Roles that can bypass workflow entirely
                                  // Different from step-level allowedRoles
                                  // Users with these roles can skip all workflow steps
steps: Array<{                   // Optional: Workflow steps (created in order provided)
  apiId: string,                  // Required: Step API ID (unique within workflow)
  displayName: string,            // Required: Step display name shown in UI
  description?: string,           // Optional: Step description
  color: ColorPalette,           // Required: Step color (visual indicator in UI)
  allowEdit: boolean,             // Required: Whether entries can be edited at this step
  returnToStep?: string,         // Optional: Previous step to return to
                                  // CANNOT be set for first step!
                                  // Must reference existing step API ID
  position?: number,              // Optional: Step order (0-based index)
                                  // If omitted, steps created in array order
                                  // If position conflicts, inserted at next available slot
  allowedRoles: string[],        // Required: Roles that can work at THIS specific step
                                  // Different from workflow-level roleOverrides
  publishStages?: string[]       // Optional: Stages that can be published from this step
                                  // Empty array or omitted = no publishing from this step
}>
})
```

</TabsItem>
  <TabsItem label="Example">

```ts
// Basic workflow with steps
client.createWorkflow({
  apiId: 'editorialWorkflow',
  displayName: 'Editorial Workflow',
  description: 'Content review and approval process',
  enabled: true,
  modelApiIds: ['Post', 'Page'],
  steps: [
    {
      apiId: 'draft',
      displayName: 'Draft',
      description: 'Work in progress',
      color: ColorPalette.BLUE,
      allowEdit: true,
      allowedRoles: ['editor', 'author'],
    },
    {
      apiId: 'review',
      displayName: 'In Review',
      description: 'Awaiting editorial review',
      color: ColorPalette.YELLOW,
      allowEdit: false,
      allowedRoles: ['editor'],
      returnToStep: 'draft',
    },
    {
      apiId: 'approved',
      displayName: 'Approved',
      description: 'Ready for publication',
      color: ColorPalette.GREEN,
      allowEdit: false,
      allowedRoles: ['editor', 'admin'],
      publishStages: ['PUBLISHED'],
    },
  ],
});
```

  </TabsItem>
</Tabs>

**Enum**
- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### updateWorkflow()

Updates an existing workflow.

**Use cases:**
- Adding/removing steps.
- Updating step configurations.
- Changing workflow models or roles.
- Modifying step order.

**Important notes:**
- `modelApiIds` uses add/remove structure.
- `roleOverrides` uses add/remove structure.
- `steps` has create/update/delete structure.
- Step `allowedRoles` uses add/remove structure
- Step `publishStages` uses add/remove structure.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateWorkflow({
  apiId: string,                    // Required: Current workflow API ID
  newApiId?: string,                // Optional: New API ID (to rename the workflow)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  enabled?: boolean,                // Optional: Whether workflow is enabled
  modelApiIds?: {                   // Optional: Update models (add/remove structure)
    modelsToAdd?: string[],         // Optional: Model API IDs to add
    modelsToRemove?: string[]        // Optional: Model API IDs to remove
  },
  roleOverrides?: {                 // Optional: Update role overrides (add/remove structure)
    rolesToAdd?: string[],          // Optional: Role IDs to add
    rolesToRemove?: string[]        // Optional: Role IDs to remove
  },
  steps?: {                         // Optional: Update workflow steps
    stepsToCreate?: Array<{         // Optional: New steps to add
      apiId: string,                // Required: Step API ID
      displayName: string,          // Required: Step display name
      description?: string,         // Optional: Step description
      color: ColorPalette,          // Required: Step color
      allowEdit: boolean,           // Required: Whether entries can be edited
      returnToStep?: string,       // Optional: Step API ID to return to
      position?: number,            // Optional: Step position
      allowedRoles: string[],       // Required: Array of role IDs
      publishStages?: string[]      // Optional: Array of stage API IDs
    }>,
    stepsToUpdate?: Array<{         // Optional: Existing steps to update
      apiId: string,                // Required: Current step API ID
      displayName?: string,         // Optional: New display name
      description?: string,         // Optional: New description
      color?: ColorPalette,         // Optional: New color
      allowEdit?: boolean,          // Optional: Whether entries can be edited
      returnToStep?: string,        // Optional: Step API ID to return to
      position?: number,            // Optional: New position
      allowedRoles?: {              // Optional: Update allowed roles (add/remove structure)
        rolesToAdd?: string[],      // Optional: Role IDs to add
        rolesToRemove?: string[]    // Optional: Role IDs to remove
      },
      publishStages?: {             // Optional: Update publish stages (add/remove structure)
        stagesToAdd?: string[],     // Optional: Stage API IDs to add
        stagesToRemove?: string[]   // Optional: Stage API IDs to remove
      }
    }>,
    stepsToDelete?: string[]        // Optional: Array of step API IDs to delete
  }
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - rename workflow and change display name
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  newApiId: 'contentWorkflow',
  displayName: 'Content Workflow',
  description: 'Updated workflow description',
});

// Update models (add/remove)
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  modelApiIds: {
    modelsToAdd: ['Page', 'Article'],
    modelsToRemove: ['Post'],
  },
});

// Add new step
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  steps: {
    stepsToCreate: [
      {
        apiId: 'archived',
        displayName: 'Archived',
        color: ColorPalette.NEUTRAL,
        allowEdit: false,
        allowedRoles: ['admin'],
      },
    ],
  },
});

// Update existing step
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  steps: {
    stepsToUpdate: [
      {
        apiId: 'review',
        displayName: 'In Review',
        color: ColorPalette.ORANGE,
        allowEdit: false,
      },
    ],
  },
});
```

  </TabsItem>
</Tabs>


**Enum**
- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### deleteWorkflow()

Deletes a workflow and all its steps. Models using this workflow revert to the default workflow.

** Use cases:**
- Removing unused workflows.
- Cleaning up test workflows.
- Restructuring workflow systems.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all workflow steps.
- May affect entries currently in workflow.
- Consider disabling workflow first before deletion.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteWorkflow({
  apiId: string  // Required: The API ID of the workflow to delete
})
```

</TabsItem>
  <TabsItem label="Example">

```ts
// Delete a workflow
client.deleteWorkflow({
  apiId: 'editorialWorkflow',
});

console.log('Workflow deleted');
```

  </TabsItem>
</Tabs>

## Webhooks

### createWebhook()

Creates a webhook.

**Use cases:**
- Notifying external systems of content changes.
- Integrating with third-party services.
- Building event-driven architectures.
- Syncing content to external databases.

**Important notes:**
- `models` and `stages` are arrays of UUIDs (not API IDs).
- Empty arrays (`[]`) mean "all models/stages" including future ones.
- `triggerActions` determines which operations trigger the webhook.
- `triggerSources` filters by source (PAT, MEMBER, PUBLIC).
- `webhookId` is a UUID, not an API ID.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createWebhook({
  name: string,                     // Required: Webhook name
  url: string,                      // Required: Webhook URL
  isActive: boolean,                // Required: Whether webhook is active
  includePayload: boolean,          // Required: Whether to include payload in request
  models: string[],                 // Required: Array of model IDs (UUIDs) - empty array for all models
  stages: string[],                 // Required: Array of stage IDs (UUIDs) - empty array for all stages
  triggerType: WebhookTriggerType,  // Required: Trigger type enum
  triggerActions: WebhookTriggerAction[], // Required: Array of trigger action enums
  description?: string,              // Optional: Description
  method?: WebhookMethod,           // Optional: HTTP method (default: POST)
  headers?: JSON,                   // Optional: Custom headers (JSON object)
  secretKey?: string,               // Optional: Secret key for webhook signature
  triggerSources?: WebhookTriggerSource[], // Optional: Array of trigger source enums
  isSystem?: boolean                // Optional: System webhook flag (only for AppTokens)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic webhook - notify on publish
client.createWebhook({
  name: 'Post Publish Notification',
  description: 'Notify marketing system when blog posts are published',
  url: 'https://api.marketing.example.com/webhooks/blog-published',
  method: WebhookMethod.POST,
  headers: {
    Authorization: 'Bearer webhook-secret-token',
    'Content-Type': 'application/json',
  },
  isActive: true,
  includePayload: true,
  models: ['post-model-uuid'], // Model ID (UUID), not API ID
  stages: ['published-stage-uuid'], // Stage ID (UUID), not API ID
  triggerType: WebhookTriggerType.CONTENT_MODEL,
  triggerActions: [WebhookTriggerAction.PUBLISH],
});

// Webhook for all models and stages
client.createWebhook({
  name: 'All Content Changes',
  url: 'https://api.example.com/webhooks/all-changes',
  method: WebhookMethod.POST,
  isActive: true,
  includePayload: true,
  models: [], // Empty array = all models (including future ones)
  stages: [], // Empty array = all stages (including future ones)
  triggerType: WebhookTriggerType.CONTENT_MODEL,
  triggerActions: [
    WebhookTriggerAction.CREATE,
    WebhookTriggerAction.UPDATE,
    WebhookTriggerAction.DELETE,
  ],
});
```

  </TabsItem>
</Tabs>

**Enums**

- `WebhookMethod`: `GET`, `POST`, `PUT`, `DELETE`
- `WebhookTriggerType`: `CONTENT_MODEL`
- `WebhookTriggerAction`: `CREATE`, `UPDATE`, `DELETE`, `PUBLISH`, `UNPUBLISH`, `TRANSITION_STEP`
- `WebhookTriggerSource`: `PAT`, `MEMBER`, `PUBLIC`

### updateWebhook()

Updates an existing webhook.

**Use cases:**
- Updating webhook URLs.
- Changing trigger conditions.
- Modifying models/stages webhook applies to.

**Important notes:**
- `models`, `stages`, `triggerActions`, `triggerSources` replace entire lists.
- `webhookId` is a UUID (not API ID).
- To add or remove items, provide a complete new list.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateWebhook({
  webhookId: string,                // Required: Webhook ID (UUID)
  name?: string,                     // Optional: New webhook name
  description?: string,              // Optional: New description
  url?: string,                      // Optional: New webhook URL
  method?: WebhookMethod,           // Optional: HTTP method
  headers?: JSON,                    // Optional: Custom headers (JSON object)
  isActive?: boolean,               // Optional: Whether webhook is active
  includePayload?: boolean,          // Optional: Whether to include payload
  models?: string[],                // Optional: Array of model IDs (UUIDs) - replaces entire list
  stages?: string[],                // Optional: Array of stage IDs (UUIDs) - replaces entire list
  triggerType?: WebhookTriggerType, // Optional: Trigger type enum
  triggerActions?: WebhookTriggerAction[], // Optional: Array of trigger action enums (replaces entire list)
  secretKey?: string,               // Optional: Secret key for webhook signature
  triggerSources?: WebhookTriggerSource[], // Optional: Array of trigger source enums (replaces entire list)
  isSystem?: boolean                // Optional: System webhook flag (only for AppTokens)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic update - change name and URL
client.updateWebhook({
  webhookId: 'webhook-uuid-here',
  name: 'Updated Webhook Name',
  url: 'https://api.example.com/webhooks/updated',
});

// Update models and stages (replaces entire list)
client.updateWebhook({
  webhookId: 'webhook-uuid-here',
  models: ['post-model-uuid', 'page-model-uuid'], // Replaces all models
  stages: ['published-stage-uuid'], // Replaces all stages
});

// Update trigger actions (replaces entire list)
client.updateWebhook({
  webhookId: 'webhook-uuid-here',
  triggerActions: [
    WebhookTriggerAction.CREATE,
    WebhookTriggerAction.UPDATE,
    WebhookTriggerAction.DELETE,
  ],
});
```

  </TabsItem>
</Tabs>

**Enums**

- `WebhookMethod`: `GET`, `POST`, `PUT`, `DELETE`
- `WebhookTriggerType`: `CONTENT_MODEL`
- `WebhookTriggerAction`: `CREATE`, `UPDATE`, `DELETE`, `PUBLISH`, `UNPUBLISH`, `TRANSITION_STEP`
- `WebhookTriggerSource`: `PAT`, `MEMBER`, `PUBLIC`

### deleteWebhook()

Deletes a webhook.

**Use cases:**
- Removing unused webhooks.
- Cleaning up test webhooks.

**Important notes:**
- Uses `webhookId` (UUID), not API ID.
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by enumerable fields.
- Must delete all enumerable fields using the enumeration first.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteWebhook({
  webhookId: string  // Required: The webhook ID (UUID)
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Delete a webhook
client.deleteWebhook({
  webhookId: 'webhook-uuid-here',
});

console.log('Webhook deleted');
```

  </TabsItem>
</Tabs>

## Sidebar elements

### createCustomSidebarElement()

Creates app-based custom sidebar element.

**Use cases:**
- Adding app integrations to models.
- Creating custom UI elements.
- Integrating third-party tools.

**Important notes:**
- Requires `appApiId` and `appElementApiId`.
- `modelApiId` specifies which model to add element to
- `position` determines order (not available in standalone method, use updateModel instead).
- `config` allows passing JSON metadata.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createCustomSidebarElement({
  modelApiId: string,               // Required: API ID of the model
  displayName: string,              // Required: Display name for the sidebar element
  appElementApiId: string,          // Required: API ID of the App element
  appApiId: string,                 // Required: API ID of the App
  description?: string,             // Optional: Description for the sidebar element
  config?: JSON                     // Optional: JSON metadata associated with the sidebar element
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic custom sidebar element creation
client.createCustomSidebarElement({
  modelApiId: 'Product',
  displayName: 'Product Analytics',
  description: 'View product analytics',
  appElementApiId: 'analytics-dashboard',
  appApiId: 'analytics-app',
  config: {
    refreshInterval: 30,
    showChart: true,
  },
});

// Custom sidebar element with minimal config
client.createCustomSidebarElement({
  modelApiId: 'Post',
  displayName: 'SEO Preview',
  appElementApiId: 'seo-preview',
  appApiId: 'seo-app',
});
```

  </TabsItem>
</Tabs>

### deleteCustomSidebarElement()

Deletes custom sidebar element.

**Use cases:**
- Removing app integrations.
- Cleaning up unused sidebar elements.

**Important notes:**
- Requires `appApiId`, `appElementApiId`, and `modelApiId`.
- Permanent deletion. This action cannot be undone.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteCustomSidebarElement({
  modelApiId: string,               // Required: API ID of the model
  appApiId: string,                 // Required: API ID of the App
  appElementApiId: string           // Required: API ID of the App element
})
```

</TabsItem>
  <TabsItem label="Example">

```ts
// Delete a custom sidebar element
client.deleteCustomSidebarElement({
  modelApiId: 'Product',
  appApiId: 'analytics-app',
  appElementApiId: 'analytics-dashboard',
});

console.log('Custom sidebar element deleted');
```

  </TabsItem>
</Tabs>

### Manage sidebar elements with updateModel()

Use the `updateModel` method on the client to manage sidebar elements.

**Use cases:**
- Bulk management of sidebar elements
- Setting positions for sidebar elements
- Managing both custom and system sidebar elements

**Important notes:**
- More powerful than standalone methods.
- Allows setting position for elements.
- Can create, update, and delete in single operation.
- System sidebar elements: `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateModel({
  apiId: string,                    // Required: Current model API ID
  sidebarElementsToUpsert?: {       // Optional: Sidebar elements to create/update/delete
    customSidebarElementsToCreate?: Array<{
      displayName: string,           // Required: Display name
      description?: string,          // Optional: Description
      config?: JSON,                 // Optional: JSON metadata
      appElementApiId: string,       // Required: API ID of the App element
      appApiId: string,              // Required: API ID of the App
      position?: number              // Optional: Position
    }>,
    systemSidebarElementsToCreate?: Array<{
      type: SystemSidebarElementType, // Required: System sidebar element type
      config?: JSON,                 // Optional: JSON metadata
      position?: number              // Optional: Position
    }>,
    sidebarElementsToUpdate?: Array<{
      displayName: string,           // Required: Current display name (identifier)
      newDisplayName?: string,       // Optional: New display name
      description?: string,          // Optional: New description
      config?: JSON,                 // Optional: New config
      position?: number              // Optional: New position
    }>,
    customSidebarElementsToDelete?: Array<{
      appApiId: string,              // Required: API ID of the App
      appElementApiId: string        // Required: API ID of the App element
    }>,
    systemSidebarElementsToDelete?: Array<{
      type: SystemSidebarElementType // Required: System sidebar element type
    }>
  }
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Add custom sidebar elements
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToCreate: [
      {
        displayName: 'Product Analytics',
        description: 'View product analytics',
        appElementApiId: 'analytics-dashboard',
        appApiId: 'analytics-app',
        position: 0,
        config: { refreshInterval: 30 },
      },
    ],
  },
});

// Add system sidebar elements
client.updateModel({
  apiId: 'Post',
  sidebarElementsToUpsert: {
    systemSidebarElementsToCreate: [
      {
        type: SystemSidebarElementType.INFORMATION,
        position: 1,
      },
      {
        type: SystemSidebarElementType.STAGES,
        position: 2,
      },
    ],
  },
});

// Update existing sidebar elements
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    sidebarElementsToUpdate: [
      {
        displayName: 'Product Analytics', // Current display name (identifier)
        newDisplayName: 'Analytics Dashboard',
        description: 'Updated analytics dashboard',
        position: 2,
      },
    ],
  },
});

// Delete custom sidebar elements
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToDelete: [
      {
        appApiId: 'old-app',
        appElementApiId: 'old-element',
      },
    ],
  },
});

// Delete system sidebar elements
client.updateModel({
  apiId: 'Post',
  sidebarElementsToUpsert: {
    systemSidebarElementsToDelete: [
      {
        type: SystemSidebarElementType.VERSIONS,
      },
    ],
  },
});

// Comprehensive sidebar management
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToCreate: [
      {
        displayName: 'New Analytics',
        appElementApiId: 'analytics-dashboard',
        appApiId: 'analytics-app',
        position: 0,
      },
    ],
    systemSidebarElementsToCreate: [
      {
        type: SystemSidebarElementType.INFORMATION,
        position: 1,
      },
    ],
    sidebarElementsToUpdate: [
      {
        displayName: 'Existing Element',
        newDisplayName: 'Updated Element',
        position: 2,
      },
    ],
    customSidebarElementsToDelete: [
      {
        appApiId: 'old-app',
        appElementApiId: 'old-element',
      },
    ],
    systemSidebarElementsToDelete: [
      {
        type: SystemSidebarElementType.VERSIONS,
      },
    ],
  },
});
```

  </TabsItem>
</Tabs>

**Enums**

- `SystemSidebarElementType`: `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`

## Conditional visibility

You can modify the visibility conditions for a number of field types, such as simple, enumerable, component, relational, union, and taxonomy fields. The `visibilityCondition` parameter is available in the following methods:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - `createSimpleField()`
        - `createEnumerableField()`
        - `createComponentField()`
        - `createRelationalField()`
        - `createUnionField()`
        - `createTaxonomyField()`
      </div>
      <div className="flex-1">
        - `updateSimpleField()`
        - `updateEnumerableField()`
        - `updateComponentField()`
        - `updateTaxonomyField()`
      </div>
    </div>

```ts
visibilityCondition?: {           // Optional: Show/hide field based on another field's value
  baseField: string,              // Required: API ID of the field that controls visibility
  operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
  enumerationValues?: string[],   // Required when baseField is enumeration type
  booleanValue?: boolean          // Required when baseField is boolean type
},
```

**Enums**
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### Change visibility condition

**Use cases:**
- Showing/hiding fields based on other field values.
- Creating dynamic forms.
- Building conditional content structures.

**Important notes:**
- `baseField` is the API ID of the controlling field.
- For enumeration fields: use `enumerationValues` array.
- For boolean fields: use `booleanValue`.
- Operators: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`.
- Can be applied to: simple fields, component fields, relational fields, union fields, taxonomy fields.

```ts
// For an enumerable baseField
client.updateSimpleField({
  apiId: "conditionalFieldOne",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "buildingMaterial", // apiId of the baseField (in this case an enumerable field)
    operator: FieldConditionOperator.IS,
    enumerationValues: ["plexiGlass"], // an array of apiId for the referenced enumerationValues
  },
});

// OR with a boolean baseField
client.updateSimpleField({
  apiId: "conditionalFieldTwo",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "isMobileApp", // apiId of the baseField (in this case a boolean field)
    operator: FieldConditionOperator.IS,
    booleanValue: true,
  },
});

// Change from one condition to another
client.updateSimpleField({
  apiId: "conditionalField",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "status", // Changed from "buildingMaterial" to "status"
    operator: FieldConditionOperator.IS,
    enumerationValues: ["PUBLISHED"], // Changed enumeration values
  },
});
```

### Remove visibility condition

**Use cases:**
- Removing conditional visibility.
- Making fields always visible.
- Simplifying form structure.

**Important notes:**
- Set `visibilityCondition: null` to remove.
- Can also omit `visibilityCondition` parameter entirely.
- Field becomes always visible (based on visibility setting).

```ts
client.updateSimpleField({
  apiId: "conditionalFieldOne",
  parentApiId: "ModelApiId",
  visibilityCondition: null,
});
```

## Apps

### createAppInstallation()

Installs an app in the environment.

**Use cases:**
- Installing apps in environment.
- Adding app functionality.
- Enabling app features.

**Important notes:**
- Requires `appApiId`.
- `config` allows passing installation configuration.
- App must exist before installation.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.createAppInstallation({
  appApiId: string,                 // Required: API ID of the app to install
  config: JSON                       // Required: App configuration (JSON object)
})
```

</TabsItem>
  <TabsItem label="Examples">

```ts
// Basic app installation
client.createAppInstallation({
  appApiId: 'analytics-app',
  config: {
    apiKey: 'your-api-key',
    enabled: true,
  },
});

// App installation with complex config
client.createAppInstallation({
  appApiId: 'seo-app',
  config: {
    apiKey: 'seo-api-key',
    settings: {
      autoGenerateMetaTags: true,
      enableSitemap: true,
      sitemapUrl: 'https://example.com/sitemap.xml',
    },
    integrations: {
      googleSearchConsole: {
        enabled: true,
        propertyId: 'property-id',
      },
    },
  },
});
```

  </TabsItem>
</Tabs>

When an app is installed via the `createAppInstallation` method, it is always installed with the `PENDING` status. Users with the necessary permissions (usually the `ADMIN` or `DEVELOPER` roles) must complete the app installation process in Hygraph Studio.

Currently, to use the `createAppInstallation` method, the app needs to exist in at least one environment within the project. Users can't use this method to install new apps, only apps that they've previously installed in an existing environment.

### updateAppInstallation()

Updates an existing app installation.

**Use cases:**
- Updating app configuration.
- Enabling or disabling app installation.
- Modifying app settings.
- Updating app integration parameters
-Refreshing app configuration

**Important notes:**
- Only valid for App Token bearer. Must be called with an App Token (not a Permanent Auth Token).
- No `appApiId` parameter. The app installation is identified by the App Token making the request.
- `config` is merged with existing config (not replaced).
- `status` controls app installation status.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.updateAppInstallation({
  config?: JSON,                    // Optional: App Installation config (merged with existing config)
  status?: AppInstallationStatus    // Optional: App Installation status
})
```

  </TabsItem>
  <TabsItem label="Examples">

```ts
// Update app configuration
client.updateAppInstallation({
  config: {
    apiKey: 'new-api-key',
    refreshInterval: 60,
    enabled: true,
  },
});

// Change app status

// Disable app installation
client.updateAppInstallation({
  status: AppInstallationStatus.DISABLED,
});

// Enable app installation
client.updateAppInstallation({
  status: AppInstallationStatus.COMPLETED,
});

// Partial config update

// Existing config: { apiKey: 'old', refreshInterval: 30, theme: 'light' }
// Update only refreshInterval
client.updateAppInstallation({
  config: {
    refreshInterval: 60, // Only this field is updated, others remain
  },
});
// Result: { apiKey: 'old', refreshInterval: 60, theme: 'light' }
```

  </TabsItem>
</Tabs>

**Enums**

- `AppInstallationStatus`: `PENDING`, `COMPLETED`, `DISABLED`.

### deleteAppInstallation()

Uninstalls an app from the environment.

**Use cases:**
- Uninstalling apps.
- Removing app functionality.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- May affect sidebar elements and app fields.

<Tabs>
  <TabsItem label="Parameters">

```ts
client.deleteAppInstallation({
  appApiId: string,                 // Required: The API ID of the app to uninstall
})
```

  </TabsItem>
  <TabsItem label="Example">

```ts
// Uninstall an app
client.deleteAppInstallation({
  appApiId: 'analytics-app',
});

console.log('App uninstalled');
```

  </TabsItem>
</Tabs>

### Custom renderers and app fields

1. To create a simple field with custom table and form renderers in an environment, first retrieve the `appApiId` and `appElementApiId` using the Management API.

    ```graphql
    query test {
      viewer {
        project(id: "<projectId>") {
          environment(name: "<environment_name>") {
            appInstallation(appApiId: "<app_name>") {
              id
              app {
                id
                apiId
                elements {
                  id
                  apiId
                  type
                }
              }
            }
          }
        }
      }
    }
    ```

2. Now, create the simple field with custom table and form renderers in the specified environment.

    ```ts
    client.createSimpleField({
      environmentId: "<environment-id>",
      parentApiId: "Car",
      apiId: "appField",
      type: "STRING",
      displayName: "App Field",
      description: null,
      initialValue: null,
      tableRenderer: "CUSTOM",
      formRenderer: "CUSTOM",
      tableExtension: null,
      formExtension: null,
      formConfig: {
        alg_text_name: "Some custom text",
        appApiId: "myapp-test",
        appElementApiId: "myAppField"
      },
      tableConfig: {
        appApiId: "myapp-test",
        appElementApiId: "myAppField"
      },
      isList: false,
      isLocalized: false,
      isRequired: false,
      isUnique: false,
      isHidden: false,
      embeddableModels: [],
      visibility: "READ_WRITE",
      isTitle: false,
      position: 8,
      validations: null,
      embedsEnabled: null,
      visibilityCondition: null
    });
    ```




---
# Management SDK quickstart

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

This quickstart shows how to install the Hygraph Management SDK, authenticate against your project, and apply schema changes programmatically.

You will start with a simple schema change, then learn how to group changes using a batch migration, which is the recommended approach for most production workflows.

By the end of this guide, you will learn how to:
- Install the Management SDK
- Create a Management SDK client
- Apply a schema change
- Apply multiple changes using a batch migration

## Prerequisites

Before you begin, make sure you have:

- A Hygraph project
- A [Permanent Auth Token](/docs/getting-started/access-and-permissions/api-access#permanent-auth-tokens) with [Management API permissions](/docs/getting-started/access-and-permissions/api-access#configure-management-api-permissions)
- Node.js 18 or later

## Install the SDK

Install the Management SDK package via npm:

```sh
npm install @hygraph/management-sdk
```

## Create a Management SDK client

Create a new file, for example `management.ts`, and initialize the client with the following parameters:

```ts
import { Client } from '@hygraph/management-sdk';

const client = new Client({
  authToken,
  endpoint,
  name, // optional
});
```

| Option                      | Description                                         |
|-----------------------------|-----------------------------------------------------|
| `authToken`                 | Permanent auth token for your project. This can be retrieved from your <Link href="https://app.hygraph.com/" target="_blank">Hygraph project</Link> in **Project Settings > Permanent Auth Tokens > Token**. Make sure the token has proper Management API permissions depending on what you plan to execute via the SDK.               |
| `endpoint`                  | Endpoint of the High Performance Content API that belongs to the environment that you will work with. The URL can be retrieved from your <Link href="https://app.hygraph.com/" target="_blank">Hygraph project</Link> in **Project Settings > Endpoints > High Performance Content API**.            |
| `name`                      | Optional identifier used for logging and debugging. Every migration has a unique name within an environment. If unspecified, a name will be generated and will be part of the response of a successful migration. Subsequent migrations with the same name in the same environment will fail.   |

For more information, [read this document](/docs/developer-guides/project/api-access).

## Add a model

The Management SDK schedules changes when methods are called. Changes are applied when you call `run()`.

The following example creates a simple content model:

```ts
client.createModel({
  apiId: 'Product',
  apiIdPlural: 'Products',
  displayName: 'Product'
})
```

If the model already exists, this call will fail.

## Add a field to the model

Next, add a field to the model:

```ts
client.createSimpleField({
  parentApiId: 'Product',
  apiId: 'name',
  displayName: 'Name',
  type: SimpleFieldType.STRING,
  isRequired: true
})
```

## Dry run a migration

The SDK supports a `dryRun` mode. We highly recommend using this to inspect the `changes` array and validate your logic before committing changes to a production environment. A migration can be dry run to preview what changes would be applied.

```ts
const changes = client.dryRun();

console.log(changes);
```

Inspect the `changes` array and validate the list of operations that will be applied to the target environment.

## Run a migration in production

The `run()` method submits all scheduled operations. It collects operations from `createModel()`, `createSimpleField()`, `applySchemaChanges()`, and submits them as a batch. The `run()` method executes all operations atomically. All operations succeed or fail together.

```ts
async run(foreground: boolean = true): Promise<MigrationInfo>
```

| Parameter                   | Type            | Description                                         |
|-----------------------------|-----------------|-----------------------------------------------------|
| `foreground`                | `boolean`       | Whether to run the migration in the foreground. If `true`, the SDK client will return the results of all actions that were executed. If `false`, a successful result only means that the actions were successfully scheduled, but not executed. Default is `true`.  |

Returns a `MigrationInfo` object with the following properties:

| Property                    | Description                                         |
|-----------------------------|-----------------------------------------------------|
| `name`                      | The name of the migration.   |

You can call the `run()` method only once per client instance. A subsequent call returns an error: `Migration has already been executed`.

### Full example

```ts
import { Client, SimpleFieldType } from '@hygraph/management-sdk';

const client = new Client({
  authToken: '<Permanent auth token>',
  endpoint: '<Content API endpoint>',
});

client.createModel({
    apiId: 'Product',
    apiIdPlural: 'Products',
    displayName: 'Product',
  });

client.createSimpleField({
    parentApiId: 'Product',
    apiId: 'name',
    displayName: 'Name',
    type: SimpleFieldType.STRING,
    isRequired: true,
  });

const result = await client.run(true);
if (result.errors) {
  throw new Error(result.errors);
}

console.log(result);
```

## Check migration status

1. Navigate to the **API Playground** in your Hygraph project.
2. In the **API selector** dropdown, select the **Management API**.
3. Run the following query to check migration status:

```graphql
query MyQuery {
  viewer {
    project(id: "<project-id>") {
      environment(name: "<environment-name>") {
        migrations {
          id
          status
          name
          errors
          createdAt
        }
      }
    }
  }
}
```

<Alert theme="warning">

At the moment, Hygraph only stores metadata for the last 30 migrations for each environment.

Every single time a new migration is applied to an environment, metadata regarding older migrations exceeding 30, sorted by time of creation, are deleted. This means changes performed by older migrations do stay in place, however, the name and other information related to this migration will no longer be available.

</Alert>

## Verify changes in Studio

After running the script, to verify the changes:
1. Open your Hygraph project.
2. Navigate to **Schema**.
3. Confirm that the `Product` model with the `name` field exists.

<Alert theme="info">

If you have a development environment where you've already made and tested schema changes, you can generate a diff and apply it directly to another environment. This mode replaces the target schema. It does not merge changes. Any schema changes that exist in the target environment but not in the source will be deleted. For more information, see the [batch migration guide](/docs/api-reference/management-sdk/management-sdk-batchmigration).

</Alert>

## Supported operations

All operations that can be executed by the SDK are listed in the TypeScript Type Definitions, <Link href="https://unpkg.com/@hygraph/management-sdk@latest/dist/src/Client.d.ts" target="_blank">Client.d.ts</Link> file. 

## Migrate from the previous SDK

To migrate from the previous SDK, which can be found <Link href="https://www.npmjs.com/package/@graphcms/management" target="_blank">here</Link>, there are a couple of changes that need to be made in order to use it with existing migration scripts.

The old SDK has been deprecated but won't be removed from NPM, so old scripts using it will still work in the future. **New features, though, will only be available in the new SDK.**

<Alert theme="warning">

While the old SDK will continue to work, it has been deprecated and support will no longer be provided for it.

</Alert>

First of all the import of the NPM package has to be changed. For this, the package name needs to be changed to `@hygraph/management-sdk`. In the previous version, the SDK offered a named export `newMigration` that could be used to create a new migration. This changed with the new version, so a new migration must be created as follows:

```ts
import { Client } from '@hygraph/management-sdk';

const migration = new Client({
  authToken: '...',
  endpoint: '...',
});
```

The general methods on the migration class stayed the same. So running or performing a `dryRun` will still work as before.

The major change are the operations that are supported to actually execute changes:

Before, the SDK was built in a fluent API style. This means you could chain operations like the following:

```ts
migration
  .createModel({
    apiId: 'Author',
    apiIdPlural: 'Authors',
    displayName: 'Author',
  })
  .addSimpleField({
    apiId: 'firstName',
    displayName: 'First Name',
    type: FieldType.String,
  });
```

The new SDK version no longer supports chaining. The reason behind that is that the SDK is now fully generated by the schema it is using to execute the migration. The previous example needs to be changed as follows:

```ts
migration.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
  displayName: 'Post',
});
migration.createSimpleField({
  apiId: 'firstName',
  displayName: 'First Name',
  type: SimpleFieldType.STRING,
  modelApiId: 'Post',
});
```

To link the second operation to the first one, that is, to create the field on the created model in the first operation, you need to pass the `modelApiId` into the operation.


---
# Components

Source: https://hygraph.com/docs/api-reference/schema/components

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

## Querying components

After a component field has been configured, it is added to the Hygraph schema and becomes immediately queryable through the API. Press `CTRL+Space` or open the Explorer view to see the available fields inside the model that contains a component field.

### Basic components

Basic component fields are queried in the same way, as you would query regular fields inside your models. In the example below, a user has a `page` model with a basic `hero` component field that has `cta`, `description` and `heroImage` fields. Here's an example of a query with this setup:

```graphql
query basicComponent {
  pages {
    id
    title
    mainText
    hero {
      #note that in the case of basic components, we're only using the component field's API ID, and we don't need to use the API ID of the component itself
      cta
      description
      heroImage {
        url
        height
        width
      }
    }
  }
}
```

The query above will return a result like this:

```json
{
  "data": {
    "pages": [
      {
        "id": "cl120a7gvu57b0bt3qw4xiv86",
        "title": "Open positions at Hygraph",
        "mainText": "Follow this link to see all of the open positions - https://jobs.hygraph.com/",
        "hero": [
          {
            "cta": "Explore vacancies!",
            "description": "There are a huge variety of positions to be filled now",
            "heroImage": {
              "url": "https://media.graphassets.com/OIi5LuhxTTOm1M2bDS9N",
              "height": 480,
              "width": 640
            }
          },
          {
            "cta": "Apply right now!",
            "description": "The application process is nice and smooth",
            "heroImage": {
              "url": "https://media.graphassets.com/bAEFpGV2S2WxiuzYcV6R",
              "height": 427,
              "width": 640
            }
          }
        ]
      }
    ]
  }
}
```

### Modular components

Modular component fields are union types “under the hood”, so querying works the same way as with relations and unions. In the example below, a user has a blogPost model with some regular fields, such as `id`, `title` and `mainText`, as well as the modular `additionalSections` component field. The modular component field has two different components: `Contributor` and `VideoBlock`. To query the two components inside the modular component field, we're going to use `... on Contributor` and `... on VideoBlock`, as we would do with a regular union type:

```graphql
query modularComponent {
  blogPost(where: { id: "cl11z0rctt6g80bt3anxt7c11" }) {
    id
    title
    mainText {
      markdown
    }
    categories {
      categoryName
    }
    additionalSections {
      __typename # if you have multiple component instances, it's recommended to use __typename to know which fields belong to which component instance.
      ... on Contributor {
        id
        name
        jobTitle
      }
      ... on VideoBlock {
        id
        title
        description
        youTubeEmbedUrl
        autoplay
      }
    }
  }
}
```

This query will return something like this:

```json
{
  "data": {
    "blogPost": {
      "id": "cl11z0rctt6g80bt3anxt7c11",
      "title": "Berlin in spring",
      "mainText": {
        "markdown": "The best time to visit the German capital is the end of April\n"
      },
      "categories": [
        {
          "categoryName": "General"
        }
      ],
      "additionalSections": [
        {
          "__typename": "VideoBlock",
          "id": "cl11z858dt6te0ftjxi5ucvwx",
          "title": "Spring in Berlin",
          "description": "Watch this video for some travelling inspiration",
          "youTubeEmbedUrl": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/aWBGxt38o4s\" title=\"YouTube video player\" frameBorder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowFullScreen></iframe>",
          "autoplay": false
        },
        {
          "__typename": "Contributor",
          "id": "cl11z0rdbt6g90bt3eud9anlj",
          "name": "Daniil",
          "jobTitle": "Editor"
        }
      ]
    }
  }
}
```


---
# Enumerations

Source: https://hygraph.com/docs/api-reference/schema/enumerations

## Overview

An enumeration (or enum for short) can be used to group values within a type. Enums can be useful to filter, and define certain content entries in your project.

For example, a product model may contain the enum `COMMODITY`, and values `Digital` and `Physical`.

Enums values can only contain alphanumeric characters, and underscores.

Learn more about [Enumerations](/docs/api-reference/schema/field-types#enumerations).

## Fetching enumeration values

You may want to fetch all possible values of an Enum you have created. You can do this via GraphQL using your projects API endpoint.

```graphql
{
  __type(name: "COMMODITY") {
    enumValues {
      name
    }
  }
}
```

## Enumerations in the UI

- [Create an enumeration](/docs/developer-guides/schema/using-enumerations#create-an-enumeration)
- [Use the demo enumeration](/docs/developer-guides/schema/using-enumerations#use-demo-enumeration)
- [Delete an enumeration](/docs/developer-guides/schema/using-enumerations#delete-an-enumeration)
- [Add an enumeration to a model](/docs/developer-guides/schema/using-enumerations#add-an-enumeration-to-a-model)

---
# Environment diffing

Source: https://hygraph.com/docs/api-reference/schema/environment-diffing

## Overview

Environment diffing is a feature in the Management API that lets you compare schemas between two environments in a project.

<Alert theme="warning">
This guide assumes the master environment is the **target** and the development environment is the **source**.

You can also use the [Management SDK method](/docs/api-reference/management-sdk/management-sdk-batchmigration) to get the diff and apply schema changes.
</Alert>

When working with multiple environments, environment diffing helps you track changes made in development compared to the master environment. This helps you identify the changes needed to align your target environment with your source environment.

## How does environment diffing work?

Right after cloning, both environments have the same schema. As you apply schema changes to your development environment, it will start to diverge. To find out what exactly those differences are and then apply them to your target environment, you can create a diff.

## 1. Get environment names

To create a diff, you need the names of the target and source environments.

<Alert theme="warning">
When using the **API Playground**, use the **API selector** dropdown to select the **Management API**.
</Alert>

The query to the `ManagementApi` looks like this:

```graphql
query MyQuery {
  viewer {
    project(id: "<your-project-id>") {
      environments {
        name
        id
      }
    }
  }
}
```

## 2. Create the diff

After getting the environment names, generate the diff. The response lists the changes needed to align the target with the source.

To differentiate between the environments `master` and `dev`, you can use the following query to the `ManagementApi`:

```graphql
{
  viewer {
    project(id: "<your-project-id>") {
      environment(name: "master") {
        diff(environmentName: "development") {
          changes
        }
      }
    }
  }
}
```

The response example above shows an array of objects (an ordered list of `BatchMigrations`), showing all the changes you need to apply to your target environment so that it's the same as your source environment.

## 3. Apply schema changes

Use the returned list to apply updates to the target environment. Here's an example mutation in the `ManagementApi`:

```graphql
mutation MyMutation($changes: [BatchMigrationChangeInput!]!) {
  submitBatchChanges(
    data: { environmentId: "<your-target-environment-id>", changes: $changes }
  ) {
    migration {
      id
    }
  }
}
```

<Alert theme="warning">
You can find your target environment ID using the first query example in this document.
</Alert>

In the above example, `$changes` is the environment variable with value equal to the changes object in the diff. This can be supplied like so:


<Tabs panelHeight={350}>
  <TabsItem label="$changes variable example">
```json
{
  "changes": [
    {
      "createModel": {
        "apiId": "Example",
        "apiIdPlural": "Examples",
        "description": "",
        "displayName": "Example",
        "previewURLs": []
      }
    },
    <add_other_operations_in_the_diff_here>
  ]
}
```
  </TabsItem>
</Tabs>

## Supported schema elements

The following schema elements are supported:

- Models
- Components
- Locales
- Simple fields
- Conditional visibility in fields
- Relational fields
- Enumerations
- Enumerable fields
- Initial values in enumeration fields
- Stages
- Union fields
- Apps
- Custom renderers and app fields
- Sidebar elements
- Remote fields
- Remote type definitions
- Remote sources

<Alert theme="warning">
**Not supported:** UI extensions.
</Alert>

### Apps in diffs

The diff accounts for app installations, generating `createAppInstallation` and `deleteAppInstallation` operations as needed.

<Tabs panelHeight={400}>
  <TabsItem label="createAppInstallation & deleteAppInstallation example">
```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "id": "{envId}",
          "diff": {
            "changes": [
              {
                "createAppInstallation": {
                  "appApiId": "analytics-app",
                  "displayName": "Analytics App",
                  "configuration": {
                    "apiKey": null,
                    "trackingId": null
                  },
                  "status": "INCOMPLETE_SETUP"
                }
              },
              {
                "deleteAppInstallation": {
                  "appApiId": "old-seo-app"
                }
              }
            ]
          }
        }
      }
    }
  }
}
```
  </TabsItem>
</Tabs>

#### Custom renderers and app fields in diffs

When creating or updating app fields, diffing includes configurations for custom renderers, like so:

<Tabs panelHeight={400}>
  <TabsItem label="Custom renderers and app fields">
```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "id": "{envId}",
          "diff": {
            "changes": [
              {
                "createSimpleField": {
                  "apiId": "appField",
                  "parentApiId": "Car",
                  "type": "STRING",
                  "displayName": "App Field",
                  "description": null,
                  "initialValue": null,
                  "tableRenderer": "CUSTOM",
                  "formRenderer": "CUSTOM",
                  "tableExtension": null,
                  "formExtension": null,
                  "formConfig": {
                    "alg_text_name": "Some custom text",
                    "appApiId": "myapp-test",
                    "appElementApiId": "myAppField"
                  },
                  "tableConfig": {
                    "appApiId": "myapp-test",
                    "appElementApiId": "myAppField"
                  },
                  "isList": false,
                  "isLocalized": false,
                  "isRequired": false,
                  "isUnique": false,
                  "isHidden": false,
                  "embeddableModels": [],
                  "visibility": "READ_WRITE",
                  "isTitle": false,
                  "position": 8,
                  "validations": null,
                  "embedsEnabled": null,
                  "visibilityCondition": null
                }
              }
            ]
          }
        }
      }
    }
  }
}
```
  </TabsItem>
</Tabs>


#### Sidebar elements in diffs

The diff generates create, delete, or update statements for both system and custom sidebar elements within a model.

<Tabs panelHeight={400}>
  <TabsItem label="Sidebar elements">
```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "id": "{envId}",
          "diff": {
            "changes": [
              {
                "createSidebarElement": {
                  "parentApiId": "Car",
                  "apiId": "customNotes",
                  "type": "CUSTOM",
                  "displayName": "Custom Notes",
                  "config": {
                    "widgetType": "CUSTOM",
                    "helpText": "Add additional notes here"
                  },
                  "position": 3
                }
              },
              {
                "updateSidebarElement": {
                  "apiId": "status",
                  "parentApiId": "Car",
                  "newConfig": {
                    "widgetType": "CUSTOM",
                    "options": ["Draft", "Published", "Archived"]
                  }
                }
              },
              {
                "deleteSidebarElement": {
                  "apiId": "oldWidget",
                  "parentApiId": "Car"
                }
              }
            ]
          }
        }
      }
    }
  }
}
```
  </TabsItem>
</Tabs>

### Remote fields in diffs

Environment diffing manages create, delete, and update operations for remote fields, including their source selections and specific configurations.

<Tabs panelHeight={400}>
  <TabsItem label="Remote fields">
```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "id": "{envId}",
          "diff": {
            "changes": [
              {
                "createRemoteField": {
                  "apiId": "productReviews",
                  "parentApiId": "Product",
                  "displayName": "Product Reviews",
                  "description": "Fetches reviews for a product from an external API",
                  "remoteSourceId": "{remoteSourceId}",
                  "method": "GET",
                  "path": "/api/reviews/product/{{doc.productId}}",
                  "returnType": "ReviewMeta",
                  "inputArguments": [
                    {
                      "apiId": "productId",
                      "type": "STRING",
                      "isRequired": true
                    }
                  ],
                  "visibility": "READ_WRITE",
                  "isList": false,
                  "isLocalized": false,
                  "isRequired": false,
                  "isUnique": false,
                  "isHidden": false,
                  "position": 5
                }
              },
              {
                "updateRemoteField": {
                  "apiId": "externalStock",
                  "parentApiId": "Product",
                  "newConfig": {
                    "remoteFieldPath": "data.stock",
                    "type": "INTEGER"
                  }
                }
              },
              {
                "deleteRemoteField": {
                  "apiId": "legacyPrice",
                  "parentApiId": "Product"
                }
              }
            ]
          }
        }
      }
    }
  }
}
```
  </TabsItem>
</Tabs>

### Conditional visibility in diffs

Environment diffing takes into account the conditional visibility settings on all fields:

```json
"visibilityCondition": {
                    "baseField": "buildingMaterial",
                    "operator": "IS",
                    "booleanValue": null,
                    "enumerationValues": [
                      "plexiGlass"
                    ]
                  }
```

## Environment diffing limitations

Please take into account the following limitations when using environment diffing.

### Schema changes in master

Environment diffing does not merge changes. Instead, it replaces the schema in the target environment with the one from the source.

If master changes after cloning but development does not, the diff suggests deleting unmatched changes. This can lead to content loss.

<Alert theme="warning">
A diff lists operations that make the target schema match the source. Any target changes not in the source will be replaced or overwritten.

**This applies to any schema changes to your master environment**, such as adding, editing, or deleting models, fields, or sidebar widgets.
</Alert>

To avoid issues:
- Freeze schema changes in master while working in development.
- Mirror changes in both environments as you go.
- Manually review the diff before applying it to prevent unintended deletions.

**Example situations:**
- Imagine you cloned your `master` environment last week to create a `development` environment and have spent some time since then working on `development`, making changes to the schema. During that time, you also applied schema changes to your `master` environment, which you did not mirror in `development`. Later on, when using environment diffing to get the diff and apply it, the diff will find those differences, and suggest deleting the changes you made to the schema in your `master` during the last week. Remember it does not merge, but **replaces / overwrites**.
- Imagine your target environment schema has a field called **Title Field**, and after cloning you change its name to **Title** in master. In this case, environment diffing would suggest to delete **Title** and create **Title Field**. Doing this would result in schemas being the same in both environments, but you will have lost the content.
- Imagine you delete a field in your development environment, then create a new field with the same name, environment diffing would not detect them as different fields at all.

Once you get the diff, you can apply it as is or, if necessary, edit it manually before applying to avoid content loss in the case of schema changes in the target environment.

Review diff changes before applying them to ensure accuracy. **Double-check deletions to prevent content loss.**

### Required fields in diffs

If you make a field required in development, you must provide a migration value. This value replaces `null` for existing content.

![Migration value in field validations](/images/docs/api-reference/schema/env-diffing-migrationvalue.png)

In this case, environment diffing would suggest updating the field to `required`, but would not provide a migration value.

You must include it manually in the change request before applying it to prevent it from failing.

To do this, add `"migrationValue": "value"`, like so:

```json
{
  "changes": [
    {
      "createSimpleField": {
        "apiId": "newField",
        "parentApiId": "Post",
        "type": "STRING",
        "displayName": "NewField",
        "description": null,
        "initialValue": null,
        "tableRenderer": "GCMS_SINGLE_LINE",
        "formRenderer": "GCMS_SINGLE_LINE",
        "tableExtension": null,
        "formExtension": null,
        "formConfig": {},
        "tableConfig": {},
        "isList": false,
        "isLocalized": false,
        "isRequired": true,
        "isUnique": false,
        "isHidden": false,
        "embeddableModels": [],
        "visibility": "READ_WRITE",
        "isTitle": false,
        "position": 3,
        "validations": null,
        "embedsEnabled": null,
        "migrationValue": "value"
      }
    }
  ]
}
```

This way, `"value"` will replace `null` after the diff.

<Alert theme="info">
If you're working with a boolean field, you would need to pass the values `true` or `false` instead.
</Alert>

### Remote Sources with OAuth

If a remote source uses `OAuth authentication`, the diff will exclude the `clientSecret`. You must manually add the actual secret before applying the changes.

<Tabs panelHeight={230}>
  <TabsItem label="EnvDiffQuery">

```ts
query EnvDiffQuery {
  viewer {
    project(id: "8845d7cc-668d-4a5b-93d9-66d947b95fe9") {
      environment(name: "staging") {
        id
        diff(environmentName: "master") {
          changes
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Result">

```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "id": "010abb8e48c3460bb2649faa83cc3bee",
          "diff": {
            "changes": [
              {
                "createRESTRemoteSource": {
                  "debugEnabled": true,
                  "description": "",
                  "displayName": "CommerceLayer",
                  "headers": {},
                  "kind": "CommerceLayer",
                  "oAuth": {
                    "authorizationGrantType": "client_credentials",
                    "authorizationUrl": "https://hyg.commercelayer.io/oauth/token",
                    "clientId": "F5J9l-1q8SwIRRbYuY_h1Vb-pOFzJjOTcO4HfyM_XMI",
                    "clientSecret": "CLIENT_SECRET",
                    "scopes": ""
                  },
                  "prefix": "CommerceLayer",
                  "url": "https://hyg.commercelayer.io/api"
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

You must manually replace `CLIENT_SECRET` with your actual secret before applying the batch mutation.

So, for instance, this:

```json
"clientSecret": "CLIENT_SECRET",
```

Would turn into this:

```json
"clientSecret": "23sad-129132", //actual secret value
```

---
# Field configuration

Source: https://hygraph.com/docs/api-reference/schema/field-configuration

Fields define models in Hygraph. Field settings let you control how each field behaves and shape editor experience. This section describes all the configuration options available for each field in a schema, from basic attributes like display name and API ID to advanced settings for validation, localization, and visibility controls.

## Settings

Each field must have the following settings configured to be added to a model:

| Property     | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| Display name | This is what is shown to content editors throughout the application  |
| API ID       | This is what is exposed within the API as a field within your model. |
| Description  | Displays a hint for content editors and API users.                   |

Not all settings are available for all [field types](/docs/api-reference/schema/field-types).

### (Rich text fields only) Embed options

You can enable rich text embedding per field while adding or editing a Rich Text field. On the **Settings** tab, under **Field options**, select the **Enable embedding** checkbox, and then select the models that should be embedded in your Rich text field.

<Alert theme="warning">

This setting is permanent and cannot be edited after the initial save.

</Alert>

![Rich Text Options](/images/docs/api-reference/schema/rich-text-embed-options.png)

### Use as title field

You can set multiple fields as titles to appear within the relational picker instead of IDs. You cannot set a field as a title this when the field visibility is set to hidden, API only or read only.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Settings** tab, under **Field options**, select the **Use as title field** checkbox. | Add the `` isTitle:`true` `` parameter. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

![Use as a title field](/images/docs/api-reference/schema/field-configuration/use-as-title.png)

### Allow multiple values

You should select this if you wish to accept multiple values for the field. Setting multiple values for the field returns an array to the API.

<Alert theme="info">

- You can select this checkbox only during field creation, and it will be read-only after that.
- You cannot use the title field with this option.

</Alert>

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Settings** tab, under **Field options**, select the **Allow multiple values** checkbox. | Add the `` isList:`true` `` parameter. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

![Allow multiple values](/images/docs/api-reference/schema/field-configuration/allow-multiple-values.png)

### Localize field

Enabling this field allows translations per locale configured on your project.

<Alert theme="info">

You cannot use **Set initial value** with this option.

</Alert>

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Settings** tab, under **Field options**, select the **Localize field** checkbox. | Add the `` isLocalized:`true` `` parameter. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

![Localize field](/images/docs/api-reference/schema/field-configuration/localize-field.png)

### Enable variants

Enabling this field allows you to add personalized versions of the main content entry.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Settings** tab, under **Field options**, select the **Enable variants** checkbox. For more information, see our [Variants](/docs/developer-guides/schema/variants) docs. | Add the `` isVariantEnabled:`true` `` parameter. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

![Enable variants](/images/docs/api-reference/schema/field-configuration/enable-variants.png)

## Validations

Not all validation options are available for all [field types](/docs/api-reference/schema/field-types).

### Make field required

Marking a field as required prevents a content entry from being saved if the field is left empty. The API will mark this field as non-nullable.

You cannot mark a field as required when the field visibility is set to API only.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Validations** tab, select the **Make field required** checkbox. | Add the `` isRequired:`true` `` parameter. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

Note the following points:
- You can set hidden and read-only fields as required, but you cannot edit them in the content form. In this case, you need to provide a **Migration value** to avoid any errors when saving a content entry.
- You can modify this field after initial field creation. If you want to mark a field as required **after** you've created content entries based on the model, you need to provide a **Migration value**. This migration value is automatically updated in all content entries where you previously did not provide any value.
- After initial field creation, if you want to set a field as required and then unique, follow these steps:
    1. Select the **Make field required** checkbox, and provide a migration value.
    2. Go through every content entry for this model, and modify the value of the field so that it is unique across all entries.
    3. Republish all the content entries that you changed.
    4. Go back to the model, and select the **Set field as unique** checkbox.

![Make field required](/images/docs/api-reference/schema/field-configuration/make-field-required.png)

### Set field as unique

Enabling this ensures content cannot be saved if the same value exists within another entry for this field. Uniqueness is checked per **Content stage**.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Validations** tab, select the **Set field as unique** checkbox. | Add the `` isUnique:`true` `` parameter. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

Note the following points:
- You can modify this field after initial field creation.
- After field creation, if you want to set a field as unique and then required, follow these steps:
    1. First, ensure that all entries have a value set for the field and republish them.
    2. Then, select the **Make field required** checkbox.

![Set field as unique](/images/docs/api-reference/schema/field-configuration/set-field-unique.png)

### Limit character count

This validation allows you to specify the minimum and maximum number of characters, and an optional custom error message if the requirements are not fulfilled.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Validations** tab, select the **Limit character count** checkbox, and then choose one of the following options: <ul><li>**Between** - Specify a range of allowed characters by defining the minimum and maximum length </li><li>**At least** - Specify the minimum number of characters required for this field.</li><li>**No more than** - Specify the maximum number of character allowed for this field.</li></ul> | Add the `validations` object. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

![Limit character count](/images/docs/api-reference/schema/field-configuration/limit-character-count.png)

### Match a specific pattern

This validation allows you to accept a specific regular expression. To set this up, follow these steps:

1. On the **Validations** tab, select the **Match a specific pattern** checkbox.
2. From the list, choose a [pattern type](#common-patterns), and provide a regular expression. You do not need to wrap the regular expression in opening or closing slashes.
3. (Optional) Choose whether the matched pattern can be case insensitive, multiline, or single line.
4. (Optional) Provide a custom error message if the regular expression does not match the specified pattern.

![Match a specific pattern](/images/docs/api-reference/schema/field-configuration/match-field-pattern.png)

#### Common patterns

You can use an existing common pattern from the web app, or provide your own.

**URL**

```
^(http://www\.|https://www\.|http://|https://)?[a-z0-9]+([-\.]{1}[a-z0-9]+)*\.[a-z]{2,5}(:[0-9]{1,5})?(/.*)?$
```

**Phone**

```
^(?:(?:\(?(?:00|\+)([1-4]\d\d|[1-9]\d?)\)?)?[\-\.\ \\\/]?)?((?:\(?\d{1,}\)?[\-\.\ \\\/]?){0,})(?:[\-\.\ \\\/]?(?:#|ext\.?|extension|x)[\-\.\ \\\/]?(\d+))?$
```

**Email**

```
[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?
```

**Slug**

```
^[a-z0-9]+(?:[-/][a-z0-9]+)*$
```

#### Unicode characters

Hygraph field validations support unicode (non-latin) characters. You can add Unicode character classes - which typically correspond to specific alphabets - to a custom Regular Expression field validation. You can read about the syntax <Link href="https://github.com/google/re2/wiki/Syntax" target="_blank">here</Link>.

### Restrict a specific pattern

This validation option allows you to _not_ accept specific regular expression.

1. On the **Validations** tab, select the **Restrict a specific pattern** checkbox.
2. From the list, choose a [pattern type](#common-patterns), and provide a regular expression. You do not need to wrap the regular expression in opening or closing slashes.
3. (Optional) Choose whether the matched pattern can be case insensitive, multiline, or single line.
4. (Optional) Provide a custom error message if the regular expression does not match the specified pattern.

![Restrict a specific pattern](/images/docs/api-reference/schema/field-configuration/restrict-field-pattern.png)

## Advanced

Not all advanced settings are available for all [field types](/docs/api-reference/schema/field-types).

### Set initial value

You can define an initial value for content editors. This doesn't have any effect on the API when performing mutations.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Advanced** tab, select the **Set initial value** checkbox, and add the value there. | To set the initial value for a field, use the `initialValue` parameter to pass a value. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#createsimplefield).  |

![Set initial value](/images/docs/api-reference/schema/field-configuration/set-initial-value.png)

### Conditional visibility

With conditional visibility, you can show selected fields to editors only when they need them. You can still query the values of hidden fields, as conditional visibility only affects the ability to see a field in the UI. For more information on conditional visibility, see our docs [here](/docs/developer-guides/schema/conditional-fields).

![Conditional visibility inside field details](/images/docs/user-guides/conditional-fields/field-visibility-checkbox.png)

### Field visibility

Field visibility has no relation with permissions or security.

| UI                                                                              | Management SDK                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| On the **Advanced** tab, use the **Field visibility** dropdown to select an option. | To indicate field visibility, use the `visibility` parameter to pass a type. [Here's an example](/docs/api-reference/management-sdk/management-sdk-methods-reference#updatesimplefield).  |

The following options are available in the UI:
- **Read / Write** - The field will be accessible for read/write operations. Default.
- **Read only** - The field will be shown, but cannot be edited in the UI. You can update via the API if required.
- **Hidden** - The field will not be shown in the UI, but can be referenced by other fields such as [Slugs](/docs/api-reference/schema/field-types#string).
- **API only** - Field is not shown in the UI, but can be used via the API using mutations.

You can set field visibility by passing one of the following types in the Management SDK:
- `visibility: "READ_WRITE"`
- `visibility: "READ_ONLY"`
- `visibility: "HIDDEN"`
- `visibility: "API_ONLY"`

![Field visibility](/images/docs/api-reference/schema/field-configuration/field-visibility.png)


---
# Field types

Source: https://hygraph.com/docs/api-reference/schema/field-types

## Overview

Your schema is built up of GraphQL types. If you're familiar working with GraphQL, you should feel right at home. Hygraph supports all of the common GraphQL types you are used to, as well as some of its own.

You may also be interested in how input types work for filtering, ordering, paginating, and mutating data.

Here you will discover the core field types available when building your Hygraph schema. Since your schema is automatically [generated](/docs/api-reference/content-api/queries#auto-generated-queries), it is recommended you browse the [API Playground](/docs/api-reference/basics/api-playground) to get inspect all available field type definitions.

## String

Hygraph supports a few variations of the String field type. Strings are just strings, but depending on the variation you add to your model, it will reflect how it appears to content editors.

| Variant          | Description                                                                                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single line text | Most used with headings, page titles, email, etc.                                                                                                                          |
| Multi line text  | Most used with strings that require no formatting, raw text like HTML, and XML where you control the parsing.                                                              |
| Markdown         | <Link href="https://daringfireball.net/projects/markdown/syntax" target="_blank">Markdown</Link> is most used as an alternative to Rich Text. Enables advanced techniques such as <Link href="https://mdxjs.com" target="_blank">MDX</Link>. |
| Slug             | Slug template with automatic initial value generation based off existing fields.                                                                                           |

All 3 variations of the String type are queried in the same way, and return the strings of the field they represent:

<Tabs panelHeight={200}>

<TabsItem label="Request">

```graphql
{
  products {
    singleLineTextField
    multiLineTextField
    markdownField
  }
}
```

</TabsItem>

<TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "singleLineTextField": "Hygraph Mug",
        "multiLineTextField": "Welcome to Hygraph",
        "markdownField": "# Hello"
      }
    ]
  }
}
```

</TabsItem>

</Tabs>

## Rich text

The `RichText` field type is an advanced String field that returns your content in 4 different formats by default: `raw`, `HTML`, `markdown`, and `text`. `json` is also available when embeds are enabled. The Rich Text field renders an advanced `textarea` with tools to add headings, links, tables, images, lists, etc.

If you have [set up multiple values](/docs/api-reference/schema/field-configuration#allow-multiple-values) for Rich Text fields, you cannot [mark the field as required](/docs/api-reference/schema/field-configuration#make-field-required).

When a Rich Text field is added to your model, it automatically generates the following types:

```graphql
type RichText {
  raw: RichTextAST!
  html: String!
  markdown String!
  text: String!
  json: RichTextAST!
}
```

Read our dedicated document on [Rich Text](/docs/api-reference/content-api/rich-text-field) for further information.

## Integer

Integers are whole numbers, and are often used to reference price in cents, stock quantities etc.

For example, here we have products with a Int field for price:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  products {
    price
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "price": 1000
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Float

Floats are floating point numbers, and often represent fractional values. They are often used to describe values with precision, such as distance, weight, volume, etc.

For example, here we have products with a Float field for rating:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  products {
    rating
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "rating": 4.5
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Boolean

Booleans default to `null` in Hygraph, and can be `true` or `false`. You may opt to use a Boolean for specifying if a product is on sale, is part of a bundle, or a post accepts comments.

For example, here we have posts with a Boolean field for `acceptsComments`:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  products {
    acceptsComments
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "acceptsComments": true
      },
      {
        "acceptsComments": false
      },
      {
        "acceptsComments": null
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Date

The Date field type adheres to <Link href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</Link> standard. This means, October 7, 1989 is represented as 1989-10-07.

For example, here we have events with a Date for `start`:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  events {
    start
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "events": [
      {
        "start": "1989-10-07"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Date and time

Similar to the date field type, the DateTime field type adheres to <Link href="https://www.iso.org/iso-8601-date-and-time-format.html" target="_blank">ISO 8601</Link> standard.

For example, here we have events with a DateTime for `start`:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  events {
    start
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "events": [
      {
        "start": "1989-10-07T09:30:00+00:00"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## JSON

Hygraph has native field support for JSON (JavaScript Object Notation). This field is often used for storing large amounts of data from other systems.

For example, here we have products with a JSON field for `metadata`:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  products {
    metadata
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "metadata": {
          "values": [10, 20, 30],
          "analyticsId": "ifuhue398"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Asset

Assets are connected to models through a [reference](#reference) field. Assets can be any file type, not just images.

The Asset model comes its own default [asset fields](/docs/api-reference/schema/system-fields#asset-fields).

For example, here we have posts with a the Asset field for `coverImage`, querying those asset fields:

<Tabs panelHeight={320}>
  <TabsItem label="Request">

```graphql
{
  posts {
    coverImage {
      url
      handle
      fileName
      height
      width
      size
      mimeType
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "posts": [
      {
        "coverImage": {
          "url": "https://media.graphassets.com/bh4xr7efSZyBh4iVeGQq",
          "handle": "bh4xr7efSZyBh4iVeGQq",
          "fileName": "Examples - Swag Store.png",
          "height": 720,
          "width": 1280,
          "size": 116893,
          "mimeType": "image/png"
        }
      }
    ]
  }
}
```

  </TabsItem>
  <TabsItem label="Response (PDFs)">

```json
{
  "data": {
    "ebooks": [
      {
        "file": {
          "url": "https://media.graphassets.com/pJOCAOncQO6K7azJbagS",
          "handle": "pJOCAOncQO6K7azJbagS",
          "fileName": "Hygraph eBook - Navigating Towards Tomorrow-s Content with a Headless CMS.pdf",
          "height": null,
          "width": null,
          "size": 2345835,
          "mimeType": "application/pdf"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

Learn more about [Assets](/docs/api-reference/assets/assets-overview).

## Color

The Color field is made up of HEX, <Link href="https://developer.mozilla.org/en-US/Web/CSS/color_value#rgb()_and_rgba()" target="_blank">RGBA</Link> and css color values.

```graphql
type Color {
  hex: Hex!
  rgba: RGBA!
  css: String!
}
```

| Field  | Type      | Description                                                         |
| ------ | --------- | ------------------------------------------------------------------- |
| `hex`  | `Hex!`    | Returns a String in the format of `#ffffff`                         |
| `rgba` | `RGBA!`   | `r`, `g`, `b`, values as `RGBAHue!`, and `a` as `RGBATransparency!` |
| `css`  | `String!` | Returns in the format of `rgb(255, 255, 255)`                       |

For example, here is posts with a Color field for `backgroundColor`, in all formats:

<Tabs panelHeight={350}>
  <TabsItem label="Request">

```graphql
{
  posts {
    backgroundColor {
      hex
      rgba {
        r
        g
        b
        a
      }
      css
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "posts": [
      {
        "backgroundColor": {
          "hex": "#ffffff",
          "rgba": {
            "r": 255,
            "g": 255,
            "b": 255,
            "a": 1
          },
          "css": "rgb(255,255,255)"
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Location

The Location field type returns `latitude`, `longitude`, and `distance` Float values.

```graphql
type Location {
  latitude: Float!
  longitude: Float!
  distance(from: LocationInput!): Float!
}
```

| Field       | Type             | Description                                                |
| ----------- | ---------------- | ---------------------------------------------------------- |
| `latitude`  | `Float!`         | Geographic coordinate (north-south position on Earth)      |
| `longitude` | `Float!`         | Geographic coordinate (east-west position on Earth)        |
| `distance`  | `LocationInput!` | Distance in meters `from` the given `latitude`/`longitude` |

To query the `distance` field, you must provide `latitude` and `longitude` values for the `from` argument.

For example, here we have all shop locations, with distance from the provided latitude/longitude:

<Tabs panelHeight={300}>
  <TabsItem label="Request">

```graphql
{
  shops {
    location {
      latitude
      longitude
      distance(
        from: { latitude: 50.58153970000001, longitude: 8.665300199999999 }
      )
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "shops": [
      {
        "location": {
          "latitude": 48.7…,
          "longitude": -122.5…,
          "longitude": 8.66…
        }
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Enumerations

[Enumerations](/docs/api-reference/schema/enumerations), or enum for short, are predefined list of values. They are defined inside your GraphQL schema, and can be referenced by any of your content models.

If you have [set up multiple values](/docs/api-reference/schema/field-configuration#allow-multiple-values) for enumerations, you cannot [mark the field as required](/docs/api-reference/schema/field-configuration#make-field-required).

For example, here is an enum for products with its commodity type:

<Tabs panelHeight={180}>
  <TabsItem label="Request">

```graphql
{
  products {
    commodity
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "commodity": "Digital"
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Taxonomies

[Taxonomies](/docs/api-reference/schema/taxonomies) are a group of terms arranged in a hierarchical structure. They are defined inside your GraphQL schema, and can be referenced by any of your content models.

If you have [set up multiple values](/docs/api-reference/schema/field-configuration#allow-multiple-values) for taxonomies, you cannot [mark the field as required](/docs/api-reference/schema/field-configuration#make-field-required).

For example, here is a taxonomy for the `products` model which has a `category` taxonomy field. The category taxonomy field uses the `Clothes` taxonomy. In the GraphQL schema, `category.value` is the taxonomy node attached to the entry, and `category.path` is an array of the full path up to the assigned node.

<Tabs panelHeight={240}>
  <TabsItem label="Request">

```graphql
query MyQuery {
  productPage(where: {id: $ProductID}) {
    category {
      value
      path {
        value
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "productPage": {
      "category": {
        "path": [
          {
            "value": "Clothes"
          },
          {
            "value": "Women"
          },
          {
            "value": "Pants"
          },
          {
            "value": "Casual"
          }
        ],
        "value": "Casual"
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Reference

References, often referred as relations, are a powerful field type that allows you to connect one or more models together, and even reference multiple models as a single field type with GraphQL Union Types.

For example, here we have an example of querying all products, with categories they belong to.

<Tabs panelHeight={200}>
  <TabsItem label="Request">

```graphql
{
  products {
    name
    category {
      name
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "products": [
      {
        "name": "ACME Hammer",
        "category": [
          {
            "name": "ACME Products"
          },
          {
            "name": "Shop Tools"
          }
        ]
      },
      {
        "name": "ACME Shovel",
        "category": [
          {
            "name": "ACME Products"
          },
          {
            "name": "Garden Tools"
          }
        ]
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

### One-way references

One-way references - also called unidirectional relations - only exist in one direction. This type of reference is most useful when there is no need to know where a model is being referenced from, such as a model that is used many times. One-way references only show up on the model for which the reference is configured, and can only be queried from that side as well. This also means that for one-way references, no reverse field is configured on the referenced model. With one-way references, the content editor UI is kept clean by not showing irrelevant relations where they are not needed.

One-way references come in two forms:

#### To one

For example, a category that can have only one product.

#### To many

For example, a category that can have multiple products.

### Two-way references

Two-way references - alternatively known as bidirectional relations - exist in two directions. This type of reference is useful for use cases where both sides of the reference are relevant, and need to be edited or queryable. Two-way references are configured and show up on both the _referencing_ and _referenced_ models, and can be queried from either side.

Two-way references come in four forms:

#### One to one

For example, a category can only have one product, and one product can only have one category.

#### One to many

For example, a category can have multiple products, but a product cannot belong to multiple categories.

#### Many to one

For example, a category has one product, but a product can belong to multiple categories.

#### Many to many

For example, a category can have many products, and products can belong to many categories.

### Union

GraphQL Union Types are great for referencing different models as a single field.

For example, here we have a typical GraphQL query for fetching `blocks` on a page.

This field is configured to be either of type `Hero`, `Grid`, and/or `Gallery`:

```graphql
{
  pages {
    blocks {
      __typename
      ... on Hero {
        title
        ctaLink
      }
      ... on Grid {
        title
        subtitle {
          markdown
        }
      }
      ... on Gallery {
        photos {
          url
          handle
        }
      }
    }
  }
}
```

Please note that unions are always two-way references.

## Remote fields

Remote fields connect specific remote data to an entry of that model. Remote fields are always related to a single remote source, and a single custom type. RESTful remote fields are configured with a path to a specific endpoint in the remote source, such as user details from Github, or price & availability from Shopify. GraphQL remote fields allow to select the entrypoint to the schema (query).

### GraphQL remote field

The GraphQL remote field requires a GraphQL Remote Source to be configured on your project. You can find out how to create a Remote Source [here](/docs/developer-guides/remote-data/remote-sources#add-a-remote-source).

The Field allows you to make a request (HTTP GET or POST) to a remote GraphQL API and to specify the query entrypoint.

[Learn more about adding a remote field to your model](/docs/developer-guides/remote-data/remote-content#add-remote-field)

#### Existing field variable in non-string arguments

![Existing field variable in non-string arguments](/images/docs/api-reference/schema/field-types-cast-int.png)

In order to support existing field variables in non-string arguments, the `{{!cast=<type>}}` syntax can be used to indicate that the resulting data should be forwarded as is.

<Alert theme="warning">
Please note that there is no post processing done on the data after filling in the existing field variable.
</Alert>

Let's say our remote GraphQL API accepts an `int` argument, which we want to get filled in from an `int` field called `n` that already exists on the model we are creating the remote field on.

When specifying the template, we can add the handlebars comment `{{!cast=<type}}` to specify what type the value resulting from our template is, so the API will forward the raw data value to the remote API.

In this example we use `{{!cast=int}}` to forward the raw `int` value.

```graphql
query example {
  assets(first: "{{doc.n}}{{!cast=int}}") {
    ...EntryPoint
  }
}
```

The resulting query shows what will be sent when we execute the remote field, which is raw `1`.

```graphql
query example {
  assets(last: 1) {
    ...EntryPoint
  }
}
```

The resulting query matches what the remote API expects.

**If we did not use the casting handlebars comment, the remote fields query template would look like this:**

```graphql
query example {
  assets(first: "{{doc.n}}") {
    ...EntryPoint
  }
}
```

When the remote field gets executed, the template gets filled in with the current document's `n` value. The resulting query would look like this:

```graphql
query example {
  assets(last: "1") {
    ...EntryPoint
  }
}
```

We mentioned before that our remote API accepts an `int` for the last argument, but our API now sends it as a `string`. Therefore, we would wrongly pass `"1"` instead of the desired `1`.

### REST remote field

In order to use a REST remote field, a REST Remote Source has to be present on the project. You can find out how to create a Remote Source [here](/docs/developer-guides/remote-data/remote-sources#add-a-remote-source).

The REST remote field allows to specify the API path to which a request (GET or POST) should be sent to.

[Learn more about adding a remote field to your model](/docs/developer-guides/remote-data/remote-sources#add-a-remote-source)

## Field visibility

Hygraph field types allow for different visibility options via the `Advanced` tab during field creation. Below is a reference for the different options and how they are different.

| Option       | Description                                                                                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read / Write | Default option, the field will be accessible for read/write purposes.                                                                                                                 |
| Read Only    | Field is shown but cannot be edited in the UI, updates can only be done via API.                                                                                                      |
| Hidden       | The field is not shown in the UI, but can be referenced by other fields such as [Slugs](/docs/api-reference/schema/field-types#string). |
| API Only     | Field is not shown in the UI, can be read and updated exclusively from the API.                                                                                                       |

Note that these options are available for all field types except for [References](/docs/api-reference/schema/field-types#reference).

<Alert theme="info">
Field visibility has no relation with permissions or security and should not be used for those purposes.
</Alert>


---
# Models

Source: https://hygraph.com/docs/api-reference/schema/models

Your schema is defined by the models you create, and [fields](/docs/api-reference/schema/field-types) you add. Inside the schema builder, you can add fields, create relationships between models, and much more.

<Alert theme="info" title="Pro Tip">
All changes to your schema are immediately available via GraphQL.
</Alert>

## Create a model

All models have the following settings:

| Property      | Example      | Description                                                     |
| ------------- | ------------ | --------------------------------------------------------------- |
| Display name  | `Post`       | The name displayed inside Hygraph, and content editors.         |
| API ID        | `Post`       | The name for fetching a single entry                            |
| Plural API ID | `Posts`      | The name for fetching multiple entries                          |
| Description   | `Blog posts` | Optional hint for content editors when interacting with fields. |

Hygraph will automatically scaffold default values for `API ID`, and `Plural API ID` based on the `Display name`. These values will be available via the API as camel case.

---

For example, let's imagine we have the model `Post`. The following queries, and mutations would be generated by the API automatically, as well as custom input types:

- `post`
- `posts`
- `postVersion`
- `postsConnection`
- `createPost`
- `updatePost`
- `deletePost`
- `upsertPost`
- `publishPost`
- `unpublishPost`
- `updateManyPostsConnection`
- `deleteManyPostsConnection`
- `publishManyPostsConnection`
- `unpublishManyPostsConnection`

Learn more about [queries](/docs/api-reference/content-api/queries), and [mutations](/docs/api-reference/content-api/mutations).

## Edit a model

You can at any time update the settings, and [Preview URLs](#preview-urls) for your content models from within the schema builder.

## Delete a model

For each of the content models you have created, you can choose to update, or delete from the schema builder.

Deleting a model will also delete all of the content entries.

## Adding fields

You can add fields to all custom models, and the system Asset model by selecting the [field type](/docs/api-reference/schema/field-types) from the fields list when viewing a model.

## System fields

All models have system fields. You don't need to add an ID, created, or updated timestamp. These are managed by Hygraph automatically.

Learn more about [system fields](/docs/api-reference/schema/system-fields).

## Preview URLs

It's most common to create a preview URL for models that represent a page, and have a field such as a slug.

The fields on your model are available to use within the URL template. For example, a `Post` model may have the following preview URLs:

| Preview name      | URL template                                             |
| ----------------- | -------------------------------------------------------- |
| `Production`      | `https://hygraph.com/blog/{slug}`                        |
| `Staging`         | `https://staging.hygraph.com/blog/{slug}`                |
| `Next.js Preview` | `https://hygraph.com/api/preview?secret=abc&slug={slug}` |

## Embedded types

All models can be embedded into the [Rich Text Field Type](/docs/api-reference/schema/field-types#rich-text) via a configuration setting. On the API side, we create a union relation that references the selected model.


---
# Schema as code

Source: https://hygraph.com/docs/api-reference/schema/schema-as-code

## Overview

Schema as code is a feature in the Management API and Management SDK that lets you generate code for your existing project schema. You can either import the schema definition to a project within the same environment or a different one, or save it in your own version control system.

Schema as code always extracts your complete project schema. There's no option to export just one model or component. Because importing is additive, you can edit the generated code to specific elements before applying it, but you're responsible for spotting dependencies and naming conflicts yourself. [Import schema elements](/docs/developer-guides/schema/import-schema) in Studio instead for a list of elements to pick from, automatic dependency resolution, and automatic conflict resolution that renames the incoming element for you.

## How do you extract project schema as code?

## 1. Get the environment name

First, you need the environment name. For this query, you need to provide the project ID. You can find the Project ID in [Project settings](/docs/developer-guides/project/manage-project-info) or in the project URL - `https://app.hygraph.com/<projectId>/<environmentId>/`.

<Alert theme="warning">
  In the **API Playground**, use the **API selector** dropdown to select the
  **Management API**.
</Alert>

The query to the `Management Api` looks like this:

```graphql
query MyQuery {
  viewer {
    project(id: "<your-project-id>") {
      environments {
        name
        id
      }
    }
  }
}
```

## 2. Generate schema as code

After getting the environment name, generate the project schema as code. Run this query using the **Management API**.

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
query schemaAsCode {
  viewer {
    project(id: "<your-project-id>") {
      environment(name: "<your-environment-name>") {
        schemaDefinition
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "schemaDefinition": [
            {
              "createModel": {
                "apiId": "Post",
                "apiIdPlural": "Posts",
                "description": "",
                "displayName": "Post"
              }
            },
            {
              "createRelationalField": {
                "apiId": "image",
                "parentApiId": "Post",
                "type": "ASSET",
                "displayName": "Image",
                "description": null,
                "isList": false,
                "isRequired": false,
                "formRenderer": "GCMS",
                "formExtension": null,
                "formConfig": {},
                "tableRenderer": "GCMS",
                "tableExtension": null,
                "tableConfig": {},
                "reverseField": {
                  "apiId": "imagePost",
                  "modelApiId": "Asset",
                  "displayName": "imagePost",
                  "description": null,
                  "isList": true,
                  "visibility": "API_ONLY",
                  "isUnidirectional": false,
                  "position": 1
                },
                "visibility": "READ_WRITE",
                "visibilityCondition": null,
                "position": 2,
                "isVariantEnabled": false
              }
            },
            {
              "createSimpleField": {
                "apiId": "content",
                "parentApiId": "Post",
                "type": "RICHTEXT",
                "displayName": "Content",
                "description": null,
                "initialValue": null,
                "tableRenderer": "GCMS",
                "formRenderer": "GCMS",
                "tableExtension": null,
                "formExtension": null,
                "formConfig": {},
                "tableConfig": {},
                "isList": false,
                "isLocalized": false,
                "isRequired": false,
                "isUnique": false,
                "isHidden": false,
                "embeddableModels": [
                  "Asset"
                ],
                "visibility": "READ_WRITE",
                "isTitle": false,
                "position": 1,
                "validations": null,
                "embedsEnabled": true,
                "visibilityCondition": null,
                "isVariantEnabled": false
              }
            },
            {
              "createSimpleField": {
                "apiId": "title",
                "parentApiId": "Post",
                "type": "STRING",
                "displayName": "Title",
                "description": null,
                "initialValue": null,
                "tableRenderer": "GCMS_SINGLE_LINE",
                "formRenderer": "GCMS_SINGLE_LINE",
                "tableExtension": null,
                "formExtension": null,
                "formConfig": {},
                "tableConfig": {},
                "isList": false,
                "isLocalized": false,
                "isRequired": false,
                "isUnique": false,
                "isHidden": false,
                "embeddableModels": [],
                "visibility": "READ_WRITE",
                "isTitle": true,
                "position": 0,
                "validations": null,
                "embedsEnabled": null,
                "visibilityCondition": null,
                "isVariantEnabled": false
              }
            }
          ]
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

The response lists the complete project schema definition in the specified environment. You can now save this schema definition in your version control system, or import the schema in another project.

## 3. (Optional) Import schema to another project

<Alert theme="warning" title="Before you import the schema to another project:">

    - Ensure that the project you are importing the schema into does not contain
    any existing entities with the same names as those in the new schema. If any
    such entry exists, your schema import will fail.

    - Verify that the target project has sufficient
    <a href="/docs/developer-guides/project/update-billing#commercial-limits">commercial limits</a> for all the entities to be imported, else your import will fail.

</Alert>

In Studio, navigate to the project that you want to import the schema. This project can be in the same or a different environment. In the **API Playground**, use the **API selector** dropdown to select the **Management API**.

Here's an example mutation in the `ManagementApi`. You can find the target environment ID by using the query in [Step 1](#1-get-the-environment-name).

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
mutation ApplySchemaDefinitionMutation(
  $schemaDefinition: [BatchMigrationChangeInput!]!
) {
  submitBatchChanges(
    data: { environmentId: "<your-environment-id>", changes: $schemaDefinition }
  ) {
    migration {
      id
      status
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Variable">

```json
{
  "schemaDefinition": [
    {
      "createModel": {
        "apiId": "Post",
        "apiIdPlural": "Posts",
        "description": "",
        "displayName": "Post"
      }
    },
    {
      "createRelationalField": {
        "apiId": "image",
        "parentApiId": "Post",
        "type": "ASSET",
        "displayName": "Image",
        "description": null,
        "isList": false,
        "isRequired": false,
        "formRenderer": "GCMS",
        "formExtension": null,
        "formConfig": {},
        "tableRenderer": "GCMS",
        "tableExtension": null,
        "tableConfig": {},
        "reverseField": {
          "apiId": "imagePost",
          "modelApiId": "Asset",
          "displayName": "imagePost",
          "description": null,
          "isList": true,
          "visibility": "API_ONLY",
          "isUnidirectional": false,
          "position": 1
        },
        "visibility": "READ_WRITE",
        "visibilityCondition": null,
        "position": 2,
        "isVariantEnabled": false
      }
    },
    {
      "createSimpleField": {
        "apiId": "content",
        "parentApiId": "Post",
        "type": "RICHTEXT",
        "displayName": "Content",
        "description": null,
        "initialValue": null,
        "tableRenderer": "GCMS",
        "formRenderer": "GCMS",
        "tableExtension": null,
        "formExtension": null,
        "formConfig": {},
        "tableConfig": {},
        "isList": false,
        "isLocalized": false,
        "isRequired": false,
        "isUnique": false,
        "isHidden": false,
        "embeddableModels": [
          "Asset"
        ],
        "visibility": "READ_WRITE",
        "isTitle": false,
        "position": 1,
        "validations": null,
        "embedsEnabled": true,
        "visibilityCondition": null,
        "isVariantEnabled": false
      }
    },
    {
      "createSimpleField": {
        "apiId": "title",
        "parentApiId": "Post",
        "type": "STRING",
        "displayName": "Title",
        "description": null,
        "initialValue": null,
        "tableRenderer": "GCMS_SINGLE_LINE",
        "formRenderer": "GCMS_SINGLE_LINE",
        "tableExtension": null,
        "formExtension": null,
        "formConfig": {},
        "tableConfig": {},
        "isList": false,
        "isLocalized": false,
        "isRequired": false,
        "isUnique": false,
        "isHidden": false,
        "embeddableModels": [],
        "visibility": "READ_WRITE",
        "isTitle": true,
        "position": 0,
        "validations": null,
        "embedsEnabled": null,
        "visibilityCondition": null,
        "isVariantEnabled": false
      }
    }
  ]
}
```

  </TabsItem>
</Tabs>

In the above example, `$schemaDefinition` is the environment variable with the value equal to the `schemaDefinition` object from the query in [Step 2](#2-generate-schema-as-code).

## Supported schema elements

The following schema elements are supported:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - Models
        - Components
        - Locales
        - Simple fields
        - Conditional visibility in fields
        - Relational fields
        - Enumerations
        - Enumerable fields
        - Initial values in enumeration fields
      </div>
      <div className="flex-1">
        - Stages
        - Union fields
        - Apps
        - Custom renderers and app fields
        - Sidebar elements
        - Remote fields
        - Remote type definitions
        - Remote sources
      </div>
    </div>

<Alert theme="warning">**Not supported:** UI extensions.</Alert>

## Limitations

Note the following limitations when using schema as code.

### Existing schema in new project

Importing a schema in a project is an additive process. This means that the existing project schema is not replaced, nor is it merged. You need to ensure that the schema does not contain any existing entities with the same names as those in the new schema. If any such entry exists, your schema import will fail.

### Remote Sources with OAuth

If a remote source uses `OAuth authentication`, the code will exclude the `clientSecret`. You must manually add the actual secret before importing the new schema.

<Tabs panelHeight={250}>
  <TabsItem label="schemaAsCodeQuery">

```graphql
query schemaAsCode {
  viewer {
    project(id: "8845d7cc-668d-4a5b-93d9-66d947b95fe9") {
      environment(name: "master") {
        schemaDefinition
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Result">

```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "schemaDefinition": [
              {
                "createRESTRemoteSource": {
                  "debugEnabled": true,
                  "description": "",
                  "displayName": "CommerceLayer",
                  "headers": {},
                  "kind": "CommerceLayer",
                  "oAuth": {
                    "authorizationGrantType": "client_credentials",
                    "authorizationUrl": "https://hyg.commercelayer.io/oauth/token",
                    "clientId": "F5J9l-1q8SwIRRbYuY_h1Vb-pOFzJjOTcO4HfyM_XMI",
                    "clientSecret": "CLIENT_SECRET",
                    "scopes": ""
                  },
                  "prefix": "CommerceLayer",
                  "url": "https://hyg.commercelayer.io/api"
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

You must manually replace `CLIENT_SECRET` with your actual secret before applying the batch mutation.

So, for instance, this:

```json
"clientSecret": "CLIENT_SECRET",
```

Would turn into this:

```json
"clientSecret": "23sad-129132", //actual secret value
```


---
# System fields

Source: https://hygraph.com/docs/api-reference/schema/system-fields

All default, and custom content types come with some managed system fields. These fields reflect certain states of your content, such as when it was last updated, or published at.

## Default model fields

These fields are included with all content models you create within Hygraph.

| Field              | Type        | Description                                        |
| ------------------ | ----------- | -------------------------------------------------- |
| `id`               | `ID!`       | Unique for each content entry                      |
| `createdAt`        | `DateTime!` | Timestamp for when the content entry was created   |
| `createdBy`        | `User`      | The user who created the content entry             |
| `updatedAt`        | `DateTime!` | Timestamp for when the content entry was updated   |
| `updatedBy`        | `User`      | The user who last updated the content entry        |
| `publishedAt`      | `DateTime!` | Timestamp for when the content entry was published |
| `publishedBy`      | `User`      | The user who last published the content entry      |
| `documentInStages` | `[model]`   | Query the current document in other stages         |

## User fields

Since the User model is included with every project, it also comes with some predefined fields, as well as all of the system fields above (but not `createdBy`, `updatedBy`, and `publishedBy`).

The User model is part of "user attribution", and is connected with content entries. This connection allows you to see who created, updated, and published content entries.

| Field         | Type        | Description                                            |
| ------------- | ----------- | ------------------------------------------------------ |
| `id`          | `ID!`       | The ID of the user                                     |
| `name`        | `String!`   | The name of the user                                   |
| `picture`     | `String`    | The profile picture URL                                |
| `kind`        | `UserKind!` | The type of user - either `MEMBER`, `PAT`, or `PUBLIC` |
| `createdAt`   | `DateTime!` | The created at date and time of the user               |
| `updatedAt`   | `DateTime!` | The last updated at date and time of the user          |
| `publishedAt` | `DateTime`  | The last published at date and time of the user        |

- If content is mutated with a [Permanent Auth Token](/docs/api-reference/basics/authorization#permanent-auth-tokens) then `kind` will return `PAT`.
- If [Public API Permissions](/docs/api-reference/basics/authorization#public-api-permissions) are enabled, and content is mutated, `kind` will return `PUBLIC`.

<Alert theme="warning">
All users will currently be members of your project. In the future they can be external users, part of a user authentication API.
</Alert>

<Tabs panelHeight={270}>
  <TabsItem label="Created by">

```graphql
{
  posts {
    createdBy {
      id
      name
      picture
      kind
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Updated by">

```graphql
{
  posts {
    updatedBy {
      id
      name
      picture
      kind
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Published by">

```graphql
{
  posts {
    publishedBy {
      id
      name
      picture
      kind
    }
  }
}
```

  </TabsItem>
</Tabs>

## Asset fields

Since the Asset model is included with every project, it also comes with some predefined fields, as well as all of the system fields above.

The Asset field type has all of the [default model fields](#default-model-fields), as well as:

| Field           | Type        | Description                                                                                               |
| --------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `url`           | `String!`   | The URL of the asset, with any [transformations](/docs/api-reference/assets/transformations). |
| `handle`        | `String!`   | The file handle.                                                                                          |
| `fileName`      | `String!`   | The document file name that was uploaded.                                                                 |
| `height`        | `Float`     | The height of the file (for images only).                                                                 |
| `width`         | `Float`     | The width of the file (for images only).                                                                  |
| `size`          | `Float`     | The total file size.                                                                                      |
| `mimeType`      | `String`    | The mime type of the file.                                                                                |
| `locale`        | `Locale!`   | The system locale enumeration for your projects locales. E.g. `en`, `de`.                                 |
| `localizations` | `[Asset!]!` | An array of localized assets for the asset you are querying.                                              |

Asset fields are localized by default, and always include the localization fields described below.

<Alert theme="info" title="Pro Tip">
While the Assets model is a system model that comes with every project by default and contains some predefined fields, you can still edit it to add fields for things like **alt text** and **captions** to your image assets.

Click [here](/docs/getting-started/fundamentals/quickstart#add-fields-to-your-model) to learn more about adding fields to a model.
</Alert>

## Localization fields

When you localize fields within Hygraph, the model will be updated to contain the following fields:

| Field           | Type            | Description                                                               |
| --------------- | --------------- | ------------------------------------------------------------------------- |
| `locale`        | `Locale!`       | The system locale enumeration for your projects locales. E.g. `en`, `de`. |
| `localizations` | `[modelName!]!` | An array of localized entries for the model you are querying.             |

Learn more about working with [Localization](/docs/api-reference/content-api/localization).

## Version history fields

One of the [auto-generated queries](/docs/api-reference/content-api/queries#auto-generated-queries) Hygraph will create is around versioning. Each time you publish content to a stage, a version is saved.

You can fetch the version history of a content entry by using the `history` field on a model. This field is managed automatically by Hygraph.

| Field       | Type        | Description                                                             |
| ----------- | ----------- | ----------------------------------------------------------------------- |
| `id`        | `ID!`       | The `id` of the content entry you are querying.                         |
| `stage`     | `Stage!`    | The content stage the content entry was published to. E.g. `PUBLISHED`. |
| `revision`  | `Int!`      | The revision number. Auto incrementing from `1`.                        |
| `createdAt` | `DateTime!` | The timestamp when the version was created.                             |

<Tabs>
  <TabsItem label="Query">

```graphql
{
  posts {
    id
    title
    history {
      id
      stage
      revision
      createdAt
    }
  }
}
```

  </TabsItem>
</Tabs>

## Connection type fields

Since Hygraph implements the Relay specification, when [fetching with Relay](/docs/api-reference/content-api/queries#fetching-with-relay) you will have some fields made available to you automatically.

For example, let's imagine we have the model `Post`. The `postsConnection` would look a little something like:

| Field       | Type           | Description                                       |
| ----------- | -------------- | ------------------------------------------------- |
| `edges`     | `[PostEdge!]!` | A list of edges, containing cursor, and the node. |
| `pageInfo`  | `PageInfo!`    | Information used for paginating nodes.            |
| `aggregate` | `Aggregate!`   | The count of records, relative to any filters.    |

### [PostEdge!]!

| Field    | Type      | Description                                                   |
| -------- | --------- | ------------------------------------------------------------- |
| `cursor` | `String!` | The edge cursor, used for paginating records.                 |
| `node`   | `Post!`   | The actual entry of the record, for example the `Post` entry. |

<Tabs panelHeight={300}>
  <TabsItem label="Query">

```graphql
{
  postsConnection {
    edges {
      cursor
      node {
        id
        name
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "postsConnection": {
      "edges": [
        {
          "cursor": "cmf1mcmbh299508ui7anmk094",
          "node": {
            "id": "cmf1mcmbh299508ui7anmk094",
            "name": "Test Hotel 1"
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

### PageInfo!

Hygraph exposes the `PageInfo` type on the field `pageInfo` for connection queries. This is useful with cursor based pagination.

| Field             | Type       | Description                                       |
| ----------------- | ---------- | ------------------------------------------------- |
| `hasNextPage`     | `Boolean!` | When paginating forwards, are there more items?   |
| `hasPreviousPage` | `Boolean!` | When paginating backwards, are there more items?  |
| `startCursor`     | `String`   | When paginating backwards, the cursor to continue |
| `endCursor`       | `String`   | When paginating forwards, the cursor to continue  |
| `pageSize`        | `Int`      | The number of items in the current page           |

<Tabs panelHeight={300}>
  <TabsItem label="Query">

```graphql
{
  postsConnection {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
      pageSize
    }
  }
}
```
  </TabsItem>
  <TabsItem label="Response">

```
{
  "data": {
    "postsConnection": {
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": false,
        "startCursor": "cmecw9abm00xg07t9tesgjqtr",
        "endCursor": "cmecw9abm00xg07t9tesgjqtr",
        "pageSize": 1
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

Learn more about [Relay cursor pagination](/docs/api-reference/content-api/pagination#relay-cursor-connections).

### Aggregate!

It is possible using the connection type query to perform an aggregate count.

| Field   | Type   | Description                                           |
| ------- | ------ | ----------------------------------------------------- |
| `count` | `Int!` | The count of results matching the query, and filters. |

<Tabs panelHeight={350}>
  <TabsItem label="Query">

```graphql
query{
  postsConnection(where: {author: {name: "John Doe"}}) {
    aggregate {
      count
    }
    edges{
      node{
        __typename
        name
        id
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "postsConnection": {
      "aggregate": {
        "count": 5
      },
      "edges": [
        {
          "node": {
            "__typename": "Location",
            "name": "Berlin",
            "id": "cmf1mcmbh299508ui7anmk094"
          }
        },
        {
          "node": {
            "__typename": "Location",
            "name": "Madrid",
            "id": "cm3955wgx5l4v07w8qo85w6c6"
          }
        },
        {
          "node": {
            "__typename": "Location",
            "name": "New York",
            "id": "cm3ouzcvl35nx07w6fbsogx9z"
          }
        },
        {
          "node": {
            "__typename": "Location",
            "name": "Paris",
            "id": "cmbqzkn5w01dt07w6pzpkk39q"
          }
        },
        {
          "node": {
            "__typename": "Location",
            "name": "Rome",
            "id": "cmdf1xsqxt3b907wblemn6015"
          }
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>


---
# Taxonomies

Source: https://hygraph.com/docs/api-reference/schema/taxonomies

## Overview

A taxonomy is a group of terms arranged in a hierarchical structure. The primary purpose of a taxonomy is to classify and logically connect related content items. This helps with content management and improves user experience with enhanced searchability.

Learn more about [Taxonomies](/docs/api-reference/schema/field-types#taxonomies).

## Fetch a taxonomy

To fetch a taxonomy, you need to access the [API Playground](/docs/api-reference/basics/api-playground) section of your Hygraph project, select `Management API` at the top of the screen, and run the following query:

<Tabs panelHeight={250}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  viewer {
    project(id: $projectId) {
      environment(id: $environmentId) {
        contentModel {
          taxonomy(id: $taxonomyId) {
            id
            apiId
            displayName
          }
        }
      }
    }
  }
}

```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "contentModel": {
            "taxonomy": {
              "id": "5f048befd53c4e4fa5e186392bf37e9c",
              "apiId": "Clothes",
              "displayName": "Clothes"
            }
          }
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Fetch taxonomy nodes

In this query, you can fetch the taxonomy nodes. The root node will return `parent:null`.

<Tabs panelHeight={380}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  viewer {
    project(id: $projectId) {
      environment(id: $environmentId) {
        contentModel {
          taxonomy(id: $taxonomyId) {
            id
            apiId
            displayName
            taxonomyNodes {
              id
              displayName
              parent {
                id
                displayName
              }
            }
          }
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "contentModel": {
            "taxonomy": {
              "id": "5f048befd53c4e4fa5e186392bf37e9c",
              "apiId": "Clothes",
              "displayName": "Clothes",
              "taxonomyNodes": [
                {
                  "id": "bf416648225e45e0b43b1fc44313e9ad",
                  "displayName": "Clothes",
                  "parent": null
                },
                {
                  "id": "cefd564fa8f04f90ac64a8bb33256fcc",
                  "displayName": "Men",
                  "parent": {
                    "id": "bf416648225e45e0b43b1fc44313e9ad",
                    "displayName": "Clothes"
                  }
                },
                {
                  "id": "dcb5c00f53254df58d9c026f127b4645",
                  "displayName": "Women",
                  "parent": {
                    "id": "bf416648225e45e0b43b1fc44313e9ad",
                    "displayName": "Clothes"
                  }
                },
                {
                  "id": "c4dfc0dbe9fe4f098dada745bf44a200",
                  "displayName": "Pants",
                  "parent": {
                    "id": "dcb5c00f53254df58d9c026f127b4645",
                    "displayName": "Women"
                  }
                },
                {
                  "id": "1afb37afd21846b7b86b7b926dd5bd11",
                  "displayName": "Shirts",
                  "parent": {
                    "id": "cefd564fa8f04f90ac64a8bb33256fcc",
                    "displayName": "Men"
                  }
                },
                {
                  "id": "ee09ad8cc1dd46038a7289b773d00877",
                  "displayName": "Formal",
                  "parent": {
                    "id": "c4dfc0dbe9fe4f098dada745bf44a200",
                    "displayName": "Pants"
                  }
                },
                {
                  "id": "bf43f35e12534f2b9d96f4812ee002a1",
                  "displayName": "Casual",
                  "parent": {
                    "id": "c4dfc0dbe9fe4f098dada745bf44a200",
                    "displayName": "Pants"
                  }
                },
                {
                  "id": "c933399a04c447c797783a24b546e4a0",
                  "displayName": "Jeans",
                  "parent": {
                    "id": "c4dfc0dbe9fe4f098dada745bf44a200",
                    "displayName": "Pants"
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

You can also retrieve the children of each node. In this case, you need to know how deep your taxonomy is. The following query returns the following taxonomy structure:
Root node > Child 1 > Child 2

<Tabs panelHeight={400}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  viewer {
    project(id: $projectId) {
      environment(id: $environmentId) {
        contentModel {
          taxonomy(id: $taxonomyId) {
            id
            apiId
            displayName
            rootNode {
              displayName
              children {
                displayName
                children {
                  displayName
                  children {
                    displayName
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "contentModel": {
            "taxonomy": {
              "id": "5f048befd53c4e4fa5e186392bf37e9c",
              "apiId": "Clothes",
              "displayName": "Clothes",
              "rootNode": {
                "displayName": "Clothes",
                "children": [
                  {
                    "displayName": "Women",
                    "children": [
                      {
                        "displayName": "Pants",
                        "children": [
                          {
                            "displayName": "Casual"
                          },
                          {
                            "displayName": "Jeans"
                          },
                          {
                            "displayName": "Formal"
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "displayName": "Men",
                    "children": [
                      {
                        "displayName": "Shirts",
                        "children": []
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

## Taxonomies in the UI

- [Create a taxonomy](/docs/developer-guides/schema/taxonomies#create-a-taxonomy)
- [Use the demo taxonomy](/docs/developer-guides/schema/taxonomies#use-demo-taxonomy)
- [Add a taxonomy to a model](/docs/developer-guides/schema/taxonomies#add-a-taxonomy-to-a-model)
- [Modify a taxonomy](/docs/developer-guides/schema/taxonomies#modify-a-taxonomy)


---
# Variants

Source: https://hygraph.com/docs/api-reference/schema/variants

## Overview

Variants and Segments work together to deliver tailored experiences to different groups of users.

After you add a Segment or a Variant, it is added to the Hygraph schema and is immediately queryable through the API. You need to access the [API Playground](/docs/api-reference/basics/api-playground) section of your Hygraph project, select `Content API` at the top of the screen, and then run the query.

## Fetch Variants

You can fetch all the Variants associated with a specific content entry.

<Tabs panelHeight={240}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  post(where: {id: "<Post_ID>"}) {
    variants {
      id
      title
      description
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "post": {
      "variants": [
        {
          "id": "cmdqahfag01fi07vwnqt0z9oe",
          "title": "Overview document for beginners",
          "description": "This is the overview document for beginners."
        },
        {
          "id": "cmdqaitbw01gs07vwfkwrnu9f",
          "title": "Overview document for intermediate users",
          "description": "This is the overview document for intermediate users."
        },
        {
        "id": "cmdqaj9hl01hk07vwpgom2lo6",
        "title": "Overview document for advanced users",
        "description": "This is the overview document for advanced users."
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

## Fetch a Variant and its linked Segments

<Tabs panelHeight={280}>
  <TabsItem label="Query">

```graphql
query myquery {
  post(where: {id: "<Post_ID>"}) {
    variants(where: {segments_some: {name: "Beginners"}}) {
      title
      description
      segments {
        name
      }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "post": {
      "variants": [
        {
          "title": "Overview document for beginners",
          "description": "This is the overview document for beginners.",
          "segments": [
            {
              "name": "Beginners"
            }
          ]
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

## Fetch a Variant from a Segment

<Tabs panelHeight={280}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  post(where: {id: "<Post_ID>"}) {
    variants(where:{segments_some:{name:"Beginners"}}) {
      title
      description
    }
    description
    title
    }
  }
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "post": {
      "variants": [
        {
          "title": "Overview document for beginners",
          "description": "This is the overview document for beginners."
        }
      ],
      "description": "This is the overview document.",
      "title": "Overview document"
    }
  }
}
```

  </TabsItem>
</Tabs>

## Fetch a Variant from multiple Segments

<Tabs panelHeight={410}>
  <TabsItem label="Query">

```graphql
query myquery {
  post(where: {id: "cmfy1om0l025y07vw1b0sc8os"}) {
    variants(
     where: {
        AND: [
          { segments_some: { slug: "intermediate" } }
          { segments_some: { slug: "returning-users" } }
        ]
      }) {
       title
       description
       segments {
         name
       }
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "post": {
      "variants": [
        {
          "title": "Overview document for Intermediate users",
          "description": "This is the overview document for intermediate users.",
          "segments": [
            {
              "name": "Intermediate"
            },
            {
              "name": "Returning users"
            }
          ]
        }
      ]
    }
  }
}
```

  </TabsItem>
</Tabs>

## Fetch all Segments

<Tabs panelHeight={200}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  segments {
    id
    name
    description
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "segments": [
      {
        "id": "cmdq856yk00l207uuzrspz4xh",
        "name": "Beginners",
        "description": "This segment is for beginners."
      },
      {
        "id": "cmdq8bdua00lg07vw8s6klbqt",
        "name": "Intermediate",
        "description": "This segment is for intermediate users."
      },
      {
        "id": "cmdq8bivp00lk07vw0h6hcjoi",
        "name": "Advanced",
        "description": "This segment is for advanced users."
      }
    ]
  }
}
```

  </TabsItem>
</Tabs>

## Fetch a Segment

You can fetch a specific Segment by providing its ID.

<Tabs panelHeight={170}>
  <TabsItem label="Query">

```graphql
query MyQuery {
  segment(where: {id: "<Segment_ID>"}) {
    name
    description
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```graphql
{
  "data": {
    "segment": {
      "description": "This segment is for beginners.",
      "name": "Beginners"
    }
  }
}
```

  </TabsItem>
</Tabs>



---
# AI Agents

Source: https://hygraph.com/docs/hygraph-ai/ai-agents

AI Agents are Hygraph's intelligent automation assistants designed to handle repetitive content workflows, such as translation, summarization, and SEO optimization. Powered by integrated large language models (LLMs), agents understand your project's schema and context, applying automation to specific fields or entries based on the configuration you define.

You configure an agent once and trigger it manually on selected entries, or let it run automatically when an entry moves through a workflow step.

Every agent run is reviewable. When an agent completes, the entry enters a read-only review state. You can approve or revert each field the agent changed before the entry returns to normal editing.

## Availability and token usage

AI Agents is available on the Enterprise plan only. Each project receives a set number of AI tokens per billing period. You can view your current usage and limits at any time on the [**Billing** page](/docs/developer-guides/project/update-billing).

## Agent types

### SEO Expert

Reviews all entry fields, including nested components, and posts a structured SEO report as a comment on the entry. The report covers content optimization, heading structure, and metadata gaps. Relation fields are excluded. Guidelines can be assigned to shape the agent's output. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines).

**Examples**
- Automatically review every blog post before it moves to the publish step and receive a structured SEO report as an entry comment.
- Identify missing meta descriptions or weak heading structures across all entry fields.
- Open a draft entry and trigger the SEO Expert from the sidebar to get a report before moving it to the review step.

### Translator agent

Translates content fields into one or more target locales, preserving tone, structure, and meaning. Custom instructions and Glossary guidelines let you control formality, handle untranslated terms, and adapt output to specific audiences. Relation fields are not translated. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines).

**Examples**
- Translate all localizable fields into French, German, and Spanish as soon as a content entry is approved in the source locale.
- Apply custom instructions such as `Keep product names untranslated` to ensure consistency across all target languages.
- Select all blog posts in a specific locale and run the Translator agent to generate translations in one pass before a product launch.
- Translate a single entry on demand when a localization request comes in outside of the normal workflow.

### Content summarizer

Generates concise summaries from one or more source fields and writes the output to a target field on the same entry. Tone, length, and focus can be guided through custom instructions. Source and target fields are configured when launching the agent, not during setup. Guidelines can be assigned to shape the agent's output. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines).

**Examples**
- Generate a 2–3 sentence excerpt from a long-form article body and write it to the `summary` field automatically.
- Produce concise overviews of product descriptions for use in listing pages or meta descriptions.
- Run the Content summarizer across an entire content type to populate a `summary` field that was previously empty.

## How to trigger agents

Each agent is configured for one triggering mode — agent runs or workflows. These are mutually exclusive.

### Agent runs

The agent is available for manual triggering from the content table or the content entry form. Select one or more entries and trigger the agent from the action bar, or open a single entry and trigger it from the **Agents** panel in the sidebar.

### Workflows

The agent runs automatically when an entry moves through a configured workflow step. No manual action is required once the workflow is set up.

## Safety guardrails

Agents only write to the fields and models you explicitly configure. They cannot delete entries, unpublish content, or modify your project structure.

The review step means no agent output reaches your published content without an editor sign-off.

## Review agent output

When an agent run completes, the entry displays a **Ready for review** status and the content entry form becomes read-only. The agent's changes are already written to the entry. The review step is where you decide what to keep.

The review presents a side-by-side diff of the original and agent output, field by field. You can approve or revert individual fields. Reverting all fields returns the entry to its exact pre-agent state.

The entry stays read-only until the review is complete. This applies both while the agent is running and while the completed run is awaiting review.

## Best practices

**Workflow agents**

- Position agents strategically in your workflow. Run agents during pre-publish or review steps so they operate on finalized content and produce the most accurate results.
- For multilingual projects, pair the SEO Expert with a Translator agent. You can run SEO analysis on the source locale first, then translate the content so localized content benefits from the same SEO feedback.
- Run the Content summarizer to generate a short excerpt, then pair it with the SEO Expert to validate the metadata before publishing.
- Always include a human review step after an agent step in workflows handling sensitive or regulated content. Agents produce output to review, not output to publish automatically.
- Monitor AI token usage on the [**Billing** page](/docs/developer-guides/project/update-billing) to stay within your plan limits. Avoid configuring agents on high-volume workflows without first estimating token consumption.

**Agent runs - bulk updates in the content table**

- Agent runs are limited to 50 entries at a time. Before running an agent on a large batch, test on 3–5 representative entries first. Review the output and confirm the agent behaves as expected before scaling up.
- Check the **Ready for review** status in the content table to track outstanding reviews after a bulk run. Entries in read-only state block editors from making updates. Clear the review queue before triggering follow-up runs.
- Scope agents to specific models rather than all models. An agent available across all models appears in every content table, which creates noise for editors working on models it was never intended for.

**Agent runs - single entry updates in the content entry form**

- Use single-entry runs from the content entry form to test a new agent configuration before using it for bulk updates. The side-by-side review gives you a clear picture of what the agent changes before you roll it out at scale.
- If an agent run produces unexpected output on a specific entry, check whether that entry has unusual field values, such as empty fields, very short content, or fields in an unexpected locale, before adjusting the agent configuration.

**General**

- Review agent configurations periodically to ensure custom instructions and assigned guidelines remain accurate. Brand voice, legal requirements, and audience context change over time.

## What's next

- [AI Agents setup](/docs/hygraph-ai/ai-agents-setup): Configure and run your first agent.

---
# Set up AI Agents

Source: https://hygraph.com/docs/hygraph-ai/ai-agents-setup

This guide walks you through configuring AI Agents in your Hygraph project. For an overview of what AI Agents can do, see [AI Agents overview](/docs/hygraph-ai/ai-agents).

## Prerequisites

Before you begin, ensure you have:

- A Hygraph project on Enterprise plan
- To run agents in workflows, you need a user with permission to configure [Content Workflows](/docs/developer-guides/project/content-workflows) and at least one [Content Workflow](/docs/developer-guides/project/content-workflows) configured in your project
- At least one content model with fields to target
- Sufficient [AI tokens](/docs/developer-guides/project/update-billing) for your billing period

## Permissions

Agents respect your project's existing role and permission configuration.

| Permission name  | Default role |
|-----------------|------------------|
| Create a new agent config | Admin |
| Update an agent config | Admin |
| Read agent config | Admin |
| Trigger an agent run | All roles |

## Step 1 - Choose an agent type

1. Go to **AI Hub > Agents**.
2. Click **Add Agent**.
3. Select one of the following agent types:
   - **SEO Expert**: Reviews entry fields and posts a structured SEO report as a comment. Relation fields are excluded.
   - **Translator agent**: Translates content fields into one or more target locales. Relation fields are not translated.
   - **Content summarizer**: Generates concise summaries from source fields.
4. Click **Set up** to configure the agent.

## Step 2 - Configure agent details

All agent types share the same **Agent details** section.

1. Enter an **Agent name**.
2. Optionally, enter a **Description**.
3. Under **Guidelines to apply**, optionally select guidelines the agent must apply. The agent defaults to no guidelines if none are selected. If no guidelines exist yet, click **Create guidelines** to set them up first. See [AI Guidelines](//docs/hygraph-ai/ai-guidelines#create-a-guideline) for setup instructions.

## Step 3 - Set usage mode

The **Usage** section controls how the agent is triggered. Select one of the following options:
- **Use in Agent runs** (selected by default)
- **Use in workflows**

### Use in Agent runs

The agent is available for manual triggering from the content table for bulk updates and the content entry form for single entry updates.

Under **Models (scope)**, optionally select the models the agent can be used on. If no models are selected, the agent defaults to all models in the project.

Models that are already used in an active workflow appear as **Not available - used in a workflow** in the selector. If a model is added to a workflow after the agent is configured, it is removed from the agent's scope automatically for manual triggering.

### Use in workflows

The agent runs automatically when an entry moves through a configured workflow step.

- Under **Workflow**, select the workflow where the agent should operate.
- Under **Workflow step**, select the step where the agent should run, or select **Add a new AI Agent step** to create one:
  1. Under **Execute after step**, choose the preceding step.
  2. Enter a **Step API ID** and **Step Display Name**.

If no workflows exist in your project yet, you need to create one first. The agent cannot be saved in workflow mode until a workflow and step are selected.

## Step 4 - Configure agent-specific settings

### SEO Expert

No additional configuration is required. Click **Add Agent**.

### Translator agent

1. Under **Languages to translate**, select one or more target locales.
2. Optionally, under **Custom instructions**, provide translation guidance, for example:
   - "Use formal tone for business audiences"
   - "Keep product names untranslated"
3. Click **Add Agent**.

<Alert theme="info">
  When the Translator agent runs, it overwrites all existing content for the selected locales, including fields that have not changed. This applies to both agent runs and workflow triggers. Review the localized content after each run to ensure no previously translated fields were unintentionally overwritten.
</Alert>

### Content summarizer

The Content summarizer has a **Configuration** section labelled "Configured when launching the agent." Source fields, target fields, and other summarizer settings are set each time the agent is launched, not during setup.

1. Optionally, under **Custom instructions**, provide output guidance, for example:
    - "Summarize in 2–3 sentences"
    - "Focus only on key benefits"
2. If you are configuring the agent for **Use in workflows**, configure the following fields. These settings are not required for **Use in Agent runs**. Instead, they are configured at runtime. See [Configure a Content summarizer agent run](#configure-a-content-summarizer-agent-run).
    - Under **Content Model**, select the model containing the fields to summarize.
    - Under **Input Fields**, select the source fields containing the content to summarize.
    - Under **Output Field**, select the field where the generated summary will be stored.
    - Under **Tone**, choose the style or tone for the generated summaries.
3. Click **Add Agent**.

#### Configure a Content summarizer agent run

When you trigger a Content summarizer agent manually, a configuration panel appears before the run starts.

1. Under **Input fields**, select the source fields containing the content to summarize.
2. Under **Entries**, review the content entries whose source fields will be summarized. This field is read-only.
3. Under **Output field**, select the field where the generated summary will be written.
4. Under **Tone**, choose the tone for the generated summary.
5. Confirm to start the run.

For bulk runs from the content table, the same configuration applies to all selected entries.

## Trigger an agent

<Alert theme="warning">
  Only one agent run can be active per entry at a time. If an entry already has an active run, or has a completed run awaiting review, it cannot be triggered again until the review is completed.
</Alert>

### Bulk updates in the content table

This applies only to agents configured for **Use in Agent runs**.

1. Go to the **Content** tab and open a view of a content model that has the agent configured for **Use in Agent runs**.
2. Select one or more entries using the checkboxes in the content table.
3. In the action bar at the bottom of the screen, click **Agents** and select the agent you want to run.

The agent runs on all selected entries, up to a maximum of 50 entries per run. The selected content entries become read-only while the agent runs.

### Single entry updates in the content entry form

This applies only to agents configured for **Use in Agent runs**.

1. Open any entry for a model that has the agent configured for **Use in Agent runs**.
2. In the right sidebar, locate the **Agents** panel.
3. Select the agent you want to run and confirm.

The content entry form becomes read-only while the agent runs.

### Workflows

This applies only to agents configured for **Use in workflows**.

An agent configured to run through workflows runs automatically when an entry moves through a configured workflow step.

## Review agent output

The content table shows agent status so you can see entries that need action without opening each one individually.

| Agent status | Description |
|---|---|
| **Pending** | Entries where an agent run is queued or in progress |
| **Ready for review** | Entries where a completed run is awaiting your review |
| **Failure** | Entries where the agent run did not complete successfully |

When an entry shows **Ready for review**, open it to check what the agent changed and approve or revert changes field by field.

When an agent run completes, the entry displays a **Ready for review** status and the content entry form remains read-only until the review is complete.

1. Open the entry that shows **Ready for review**.
2. The review screen shows a side-by-side diff of the original content and the agent's output.
3. Review each field. Approve changes you want to keep, or revert any you don't.
4. If you revert all fields, the entry returns to its exact pre-agent state.
5. Once all fields are reviewed, the entry exits read-only state and is editable again.

## Manage agents

After creating agents, you can manage and monitor them from **AI Hub → Agents**.

Each agent card displays:
- **Agent name**
- **Agent type** - SEO expert, Translator, or Content summarizer
- Target where it runs: Workflow or content table, content entry form
- **Agent configuration** details
- **Agent status**

You can perform the following tasks:

**Edit an agent:** Click the pencil icon on the agent card to update the name, description, usage mode, guidelines, or agent-specific settings.

**Enable or disable an agent:** Use the toggle on the agent card to turn the agent on or off. Disabling an agent pauses it without removing its configuration. This is useful when you want to temporarily stop an agent without losing its settings, for example during content freezes or workflow changes. Any runs already in progress when an agent is disabled will complete normally.

**Delete an agent:** Click the three-dot context menu on the agent card, then click **Delete**. Deleting an agent removes it from all workflows, and any queued or pending runs are automatically canceled. Deleting an agent is irreversible.

## Monitor agent performance
 
The **KPIs** page in **AI Hub → KPIs** gives you a real-time view of how your agents are performing. You can filter by agent and date range to focus on a specific agent or time period.

![AI Agents - KPIs](/images/docs/hygraph-ai/ai-agents-kpis.png)
 
Each agent displays the following summary metrics:
 
| Metric            | Description                                                    |
|-------------------|----------------------------------------------------------------|
| **Runs**          | Total number of times the agent has run in the selected period |
| **Success rate**  | Percentage of runs that completed without errors               |
| **Last run**      | Time elapsed since the most recent run                         |
| **Avg. duration** | Average time taken to complete a run                           |
| **AI tokens**     | Total number of AI tokens consumed in the selected period      |
 
Below the summary metrics, the **AI Tokens Trend** chart shows token consumption over time. Switch to the **Duration** tab to view run duration trends instead.
 
The **Workflow Runs** table lists individual runs with their status, result, duration, and start date. Use this to investigate specific runs that failed or produced unexpected output. Click each workflow run to view additional details.

## Troubleshooting

### Agent does not run

- Confirm the agent is active in **AI Hub > Agents**.
- For workflow agents, confirm the entry is moving through the exact workflow and step where the agent is configured.
- Verify that sufficient AI tokens remain in your billing period on the [**Billing** page](/docs/developer-guides/project/update-billing).

### Agent runs but output is unchanged

- For workflow agents, check the step order. If the agent step runs before content is populated, it has nothing to process.

### SEO report does not appear

- Check the comment section on the entry, not the fields.
- Confirm the entry completed the configured workflow step after the agent was added.

### Translation output is missing or incorrect

- Verify the target locale is enabled in your project.
- Confirm source fields contain content when the agent runs.
- Review custom instructions for conflicting or ambiguous guidance.

### Summary written to wrong field

- Open the agent configuration and confirm the target field is set correctly.
- Confirm no other agent is writing to the same target field.

### Model no longer appears in agent run scope

- The model was added to a workflow after the agent was configured. Models used in active workflows are not available for agent runs.
- Select a different model or reconfigure the workflow.

## What's next

- [Content Workflows](/docs/developer-guides/project/content-workflows): Learn more about workflow configuration.
- [MCP server](/docs/hygraph-ai/mcp-server): Explore the MCP server for direct AI assistant integration with your Hygraph project.

---
# AI Assist

Source: https://hygraph.com/docs/hygraph-ai/ai-assist

AI Assist is Hygraph's intelligent in-editor content assistant. It helps editors generate, improve, and translate content directly within the content entry experience, without needing to leave the editor or rely on developer support.

Instead of switching between tools or writing content from scratch, editors describe what they need and AI Assist produces suggestions that fit the field type, locale, and surrounding content. All suggestions are reviewed and applied by the editor, so teams stay in full control of what goes into their content.

## What you can do

### Create content

The **Create content** task generates new content for empty fields based on a short prompt. AI Assist analyzes the field type and entry context to produce suggestions that fit your content model. This is useful when starting a new entry or filling multiple empty fields at once.

**Examples**:
- Generate a headline, meta description, and introductory paragraph for a new blog post entry in a single AI Assist run.
- Populate multiple empty fields at once when creating product listings, reducing manual drafting time.

### Improve existing content

The **Improve existing content** task refines existing text for clarity, tone, and readability. AI Assist analyzes the selected fields and suggests enhanced versions while preserving the original meaning. This is useful when reviewing drafts or polishing content before publishing.

**Examples**:
- Polish a draft article for clarity and readability before it moves to editorial review.
- Standardize tone across multiple fields in an entry to ensure consistent brand voice before publishing.

### Translate content

The **Translate content** task converts existing text into one or more target locales while preserving tone, structure, and meaning. AI Assist recognizes your project's locale setup and accepts optional prompt guidance for regional style. This is useful for maintaining consistent messaging across multiple languages without leaving the editor.

**Examples**:
- Translate a product description from English into French and German directly in the editor after the source locale is approved.
- Apply regional style guidance, such as adapting a campaign message for British English spelling and tone conventions.

## Supported field types

AI Assist works with single line text, multi line text, Markdown, and rich text fields. Other field types are not shown in the field selector.

## Permissions

AI Assist is available to all users with editor access on the project. No additional role configuration is required.

| Action              | Required permission |
|---------------------|---------------------|
| Use AI Assist tasks | Editor access       |

## Availability and token usage

AI Assist is available on all Hygraph plans, with usage limits based on your plan tier. Each project receives a set number of AI tokens per billing period.

| Plan         | AI token allowance                             |
|--------------|------------------------------------------------|
| Free         | Baseline allowance to get started              |
| Self-service | Expanded limits for regular usage              |
| Enterprise   | Highest allocations for large-scale operations |

You can view your current AI token usage and limits at any time on the [**Billing** page](/docs/developer-guides/project/update-billing).

## AI Guidelines

When guidelines are assigned to an AI Assist task, the output reflects your brand vocabulary, audience expectations, and compliance constraints, not just generic AI output. 

Guidelines are created and managed by admins in **AI Hub > Configurations > Guidelines**. If the output doesn't match your expectations, ask your admin to review or add guidelines for your project. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.

## Safety guardrails

AI Assist is designed to support editors, not act independently. The following guardrails ensure editorial control is always maintained:

- All suggestions are shown in a review panel before being applied. Nothing is written to an entry without editor approval.
- AI Assist only operates on fields you explicitly select for a given task.
- AI Assist cannot publish entries or perform any action outside the content editing panel.
- Applied changes are saved like any manual edit and can be modified at any time.

## What's next

- [Use AI Assist](/docs/hygraph-ai/ai-assist-setup): Generate, improve, and translate content in the editor.

---
# Use AI Assist

Source: https://hygraph.com/docs/hygraph-ai/ai-assist-setup

This guide walks you through using AI Assist in the Hygraph content editor. For an overview of what AI Assist can do, see [AI Assist overview](/docs/hygraph-ai/ai-assist).

## Prerequisites

Before you begin, ensure you have:

| Requirement      | Details                                                                                                                                                                                                                                                                   |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Hygraph plan     | <ul><li>**Free** – Includes a baseline AI token allowance to help you get started.</li><li>**Self-service** – Offers expanded AI token limits for regular usage.</li><li>**Enterprise** – Provides the highest AI token allocations for large-scale operations.</li></ul> |
| User role        | Editor access on the project                                                                                                                                                                                                                                              |
| Supported fields | At least one single line text, multi line text, Markdown, or rich text field on the content model                                                                                                                                                                         |
| AI token budget  | Sufficient AI tokens for your billing period (check the [**Billing** page](/docs/developer-guides/project/update-billing))                                                                                                                                                |

## Permissions reference

AI Assist is enabled for all users with editor access. No additional configuration is required.

| Action              | Required permission |
|---------------------|---------------------|
| Use AI Assist tasks | Editor access       |

## Step 1 - Open AI Assist

1. In the Hygraph content editor, navigate to the entry you want to work on.
2. In the top bar, click **AI Assist**. A panel appears showing the tasks available for this entry.

## Step 2 - Choose a task

Under **Available tasks**, select the action that fits your requirement:

| Task                         | What it does                                                             |
|------------------------------|--------------------------------------------------------------------------|
| **Create content**           | Generates new content for empty fields based on a short prompt           |
| **Improve existing content** | Enhances existing text for clarity, tone, or readability                 |
| **Translate content**        | Converts text into another locale while preserving meaning and structure |

Proceed to the section below that matches your chosen task.

## Step 3 - Configure and run the task

### Create content

Use **Create content** to generate new content for one or more empty fields based on a short prompt. AI Assist produces suggestions based on your prompt and the fields you select. This is useful when creating new entries or filling multiple empty fields at once.

![AI Assist - Create content](/images/docs/hygraph-ai/ai-assist-create-content.png)

1. Under **Available tasks**, select **Create content**.
2. Under **Fields**, select the fields you want to generate content for. Up to five fields can be selected. Only single line text, multi line text, Markdown, and rich text fields are shown.
3. Under **Locale**, choose the language for the generated content.
4. Under **Guidelines to apply**, select the guidelines you want to apply to the task. If no guidelines appear in the list, none have been set up for your project yet. Ask your admin to add them.
5. Optionally, under **Tone of voice**, choose a tone.
6. In the **Prompt** field, describe what you want AI Assist to generate. Include keywords, desired structure, or tone guidance to improve the output.
7. Click **Generate**.
8. Review each suggestion in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.

### Improve existing content

Use **Improve existing content** to refine text for clarity, tone, and readability. AI Assist analyzes the selected fields and suggests enhanced versions while preserving the original meaning. This is useful when reviewing drafts, maintaining consistency across locales, or polishing your content before publishing.

![AI Assist - Improve existing content](/images/docs/hygraph-ai/ai-assist-improve-content.png)

1. Under **Available tasks**, select **Improve existing content**.
2. Under **Fields**, select the fields you want to improve. Only fields with existing content are shown. Up to five fields can be selected.
3. Under **Locale**, choose the language of the content.
4. Under **Guidelines to apply**, select the guidelines you want to apply to the task. If no guidelines appear in the list, none have been set up for your project yet. Ask your admin to add them.
5. Optionally, under **Tone of voice**, choose a tone.
6. In the **Prompt** field, describe how you want the content improved. For example: `Simplify complex sentences` or `Make the tone more conversational`.
7. Click **Generate**.
8. Review each suggestion in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.

### Translate content

Use **Translate content** to automatically translate existing text into another locale while preserving tone, structure, and meaning. AI Assist recognizes your project's locale setup and streamlines translations directly in the editor. This is useful to maintain consistent messaging across multiple languages.

![AI Assist - Translate content](/images/docs/hygraph-ai/ai-assist-translate-content.png)

1. Under **Available tasks**, select **Translate content**.
2. Under **Fields**, select the fields you want to translate. Only fields with existing content are shown. Up to five fields can be selected.
3. Under **Source locale**, choose the language of the original content.
4. Under **Target locale**, select the language to translate into. You can select more than one locale if your project supports multiple.
5. Under **Guidelines to apply**, select the guidelines you want to apply to the task. If no guidelines appear in the list, none have been set up for your project yet. Ask your admin to add them.
    - If your project has a Glossary guideline assigned, you can use it here to ensure consistent terminology across locales. 
6. Optionally, under **Tone of voice**, choose a tone.
7. Optionally, in the **Prompt** field, add regional style guidance. For example: `Adapt for British English spelling` or `Use formal register`.
8. Click **Generate**.
9. Review each translation in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.
    - If translated output uses the wrong term for a product name or technical concept, ask your admin to add it to the Glossary guideline.

## Review suggestions

After generating output for any task, AI Assist displays suggestions in the panel before writing anything to the entry.

Review each suggestion in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.

Once applied, AI Assist edits are saved like any manual update and can be edited at any time.

## Best practices

- Be specific in your prompts. Include keywords, desired structure, or tone guidance to get more accurate suggestions.
- For bulk operations, select multiple fields at once to reduce the number of AI Assist runs needed per entry.
- For translation tasks, add regional style guidance in the prompt field to handle locale-specific conventions such as spelling variants or formality levels.
- Check your AI token balance on the [**Billing** page](/docs/developer-guides/project/update-billing) if tasks stop generating. You may have reached your plan's token limit for the billing period.

## Troubleshooting

### AI Assist panel does not appear

- Confirm you have editor access on the project.
- Verify the content model includes at least one supported field type: single line text, multi line text, Markdown, or rich text.
- Refresh the page and try opening the panel again.

### No fields appear in the field selector

- For **Create content**, confirm the entry has at least one supported empty field.
- For **Improve existing content** and **Translate content**, confirm the entry has at least one supported field with existing content. Empty fields are not shown for these tasks.

### Generated content does not match expectations

- Revise your prompt to be more specific. Include the desired tone, length, structure, or keywords.
- Check the **Tone of voice** setting. If a tone is configured, it may be overriding your prompt guidance.
- Try selecting fewer fields per run to give AI Assist more focused context.

### Translation output is inaccurate or missing

- Confirm the target locale is enabled in your Hygraph project.
- Verify the source fields contain content before running the translation task.
- Add a prompt with regional style or formality guidance to improve accuracy for specific locales.

### AI Assist tasks are unavailable

- Check your AI token balance on the [**Billing** page](/docs/developer-guides/project/update-billing). Tasks are unavailable if your project has exhausted its token allowance for the billing period.

## What's next


- [AI Agents](/docs/hygraph-ai/ai-agents): Explore AI Agents to automate content tasks through manual runs or workflow steps.
- [MCP server](/docs/hygraph-ai/mcp-server): Explore the MCP server for direct AI assistant integration with your Hygraph project.

---
# Guidelines

Source: https://hygraph.com/docs/hygraph-ai/ai-guidelines

Guidelines give AI Agents project-specific context that generic AI models don't have. Without them, agents produce output for general use. With them, agents apply your brand vocabulary, audience expectations, and compliance constraints on every run.

You can create guidelines once and reuse them across agents. A single Brand Voice guideline, for example, can be assigned to both your Translator agent and your Content summarizer, so both produce output that sounds like your brand.

## Guideline categories

Hygraph provides four categories. Each maps to a distinct type of context that agents use differently.

### Audience & Context

Audience & Context guidelines define target personas, reading level, and cultural considerations. This shapes how agents frame and pitch generated output.

A technical audience guideline and a general consumer guideline produce measurably different summaries from identical source content. The difference shows up in assumed knowledge and word choice rather than structure.

**Best practices**

- Describe the audience's existing knowledge level, not just their role. "Enterprise IT administrators" tells an agent less than "Enterprise IT administrators who are familiar with SSO and directory services but may not have prior experience with headless CMS architecture." The second version reduces the chance of the agent over-explaining basics or under-explaining concepts that matter.
- Include the content's destination alongside the audience. The same reader behaves differently when scanning a product listing versus reading onboarding documentation. Specifying both narrows the agent's output range in a way that audience description alone does not.

### Brand Voice & Tone

Brand Voice & Tone guidelines define your brand's personality, writing style, and editorial rules. Agents apply this when generating or transforming text, such as summarizing, rewriting, or producing localized copy.

Write this as a concise description of how your brand communicates. "Conversational but authoritative. Short sentences. No jargon." gives an agent more to work with than a list of banned words. 

**Best practices**

- Include a positive and a negative example for your most important style rules. Telling an agent "write conversationally" is less effective than showing it one sentence that is on-brand and one that is not. The contrast gives the model a calibration point rather than an abstract instruction.
- Separate voice from tone if they differ by content type. Your brand might use the same voice across all content but use a more formal tone for legal notices than for product descriptions. Capturing that distinction in the guideline prevents agents from applying blog-post tone to compliance copy.

### Legal & Compliance

Legal & Compliance guidelines define required disclaimers, restricted language, and regulatory constraints.

Be specific. "Avoid implying guaranteed returns" is actionable. "Follow legal guidelines" is not.

**Best practices**

- Write restrictions as observable behaviors, not principles. "Do not use the word 'guarantee' or any synonym implying certainty of outcome" is enforceable by an agent. "Be careful about regulatory language" is not as it shifts interpretation to the model, which will interpret it optimistically.
- Review this guideline whenever your legal or regulatory context changes. Unlike brand voice, compliance requirements change on external schedules you don't control. A guideline that was accurate when written can become incorrect after a product update, a jurisdiction change, or a regulatory revision. Assign ownership of this guideline to someone who owns this area of responsibility.

### Glossary

Glossary guidelines define key terms, definitions, and translation rules for consistent terminology. Use this for product names, legal terminology, or brand vocabulary that must not be paraphrased or mistranslated.

A glossary is organized into term groups. Each term group represents a single concept and holds one term per locale in your project. Locales already added to a term group do not appear in the locale selector when adding further entries, so each locale can only appear once per term group. The Translator agent uses these entries directly when producing localized output.

**Best practices**

- Cover edge cases, not just obvious terms. Product names are easy. The harder wins come from abbreviations, plural forms, and terms that have acceptable translations in general usage but wrong ones in your domain. For example, "checkout" in an e-commerce context should stay as "checkout" in German, not be translated to "Kasse" (cash register), which carries the wrong meaning for an online store.
- Keep the glossary focused. Prioritize terms, such as brand names, legal designations, and UI labels, where mistranslation might cause real problems.

## Permissions

By default, Guidelines permissions are granted as follows:

| Action | Default role |
|---|---|
| Read AI guidelines | All roles |
| Create AI guidelines | Admin |
| Update AI guidelines | Admin |
| Delete AI guidelines | Admin |

Non-admin users can view existing guidelines and see which guidelines are assigned to an agent, but cannot create, edit, or delete them. If your team needs editors or other roles to manage guidelines, an Admin can update these permissions in **[Project Settings > Roles & Permissions](/docs/developer-guides/project/roles-and-permissions)**.

## Limits

Plan your guideline budget before creating them. A project running three agents could quickly exhaust the project limit with no overlap. Alternatively, you can share guidelines strategically to cover more ground.

| Limit | Free | Self-service | Enterprise |
|---|---|---|---|
| Guidelines per project (excluding glossaries) | 3 | 8 | 8 |
| Characters per guideline | 4,000 | 8,000 | 8,000 |
| Glossaries per project | 1 | 3 | 3 |
| Terms per glossary | 50 | 150 | 150 |
| Versions per guideline | 5 | 10 | 10 |
| Guidelines per agent | Not applicable | Not applicable | 3 |
| Guidelines per AI Assist task | 1 | 3 | 3 |

Free or self-service plan users can use guidelines for AI Assist tasks only.

## Create a guideline

### Markdown guideline

Markdown guidelines cover **Audience & Context**, **Brand Voice & Tone**, and **Legal & Compliance**.

1. Go to **AI Hub > Configurations > Guidelines**.
2. Click **Add Guideline** and select a category: **Audience & Context**, **Brand Voice & Tone**, or **Legal & Compliance**.
3. Enter a **Name**, and click **Add**.
4. Write your guideline content in Markdown in the **Document** tab. You can use headings, lists, tables, and images to structure the guideline.
5. Click **Save**.

The guideline is immediately available to assign to any agent or use in any AI Assist task in the project.

### Glossary

1. Go to **AI Hub > Configurations > Guidelines**.
2. Click **Add Guideline** and select **Glossary**.
3. Enter a **Name**, and click **Add Glossary**.
4. Add your terms. See [Add terms to a glossary](#add-terms-to-a-glossary) or [import a glossary from a template](#import-a-glossary-from-a-template).
5. Click **Save**.

<Alert theme="warning">
  The same concept can exist in multiple term groups with different translations. For example, "house" mapped to "Haus" in one group and "Hause" in another. Hygraph does not flag this. Review your glossary before assigning it as conflicting entries might produce unpredictable translation output.
</Alert>

The glossary is immediately available to assign to any agent or use in any AI Assist task in the project.

#### Add terms to a glossary

Terms are organized into term groups. Each term group represents one concept and holds one term per locale.

**To add a term group:**

1. Click **Add term group**.
2. Enter the term and choose the locale.
3. Enter an optional **Definition**.
4. Click **Add**.

**To add terms for additional locales to the same term group:**

1. Click **+** next to the term group.
2. Enter the term and choose the locale. Locales already added to this term group do not appear in the selector.
3. Enter an optional **Definition**.
4. Click **Add**.

Repeat until all required locales are covered for that term group. To add another concept, click **Add term group** again.

You can also edit or delete term groups and terms using the following actions:
- Edit a term group name: Click the <img src="/images/docs/developer-guides/edit.png" class ="inline"></img> (pencil icon) next to the term group name.
- Edit an individual term: Click the <img src="/images/docs/developer-guides/edit.png" class ="inline"></img> (pencil icon) next to that term entry.
- Delete a term group or individual term: Click the <img src="/images/docs/developer-guides/delete.png" class ="inline"></img> (delete icon) next to the item you want to remove.

#### Import a glossary from a template

1. On the Glossary creation screen, click **Download CSV template**.
2. Fill in your term entries in the spreadsheet. Each row requires a **Term Group**, **Locale**, and **Term**. **Definition** is optional.
3. If the **Import** button is not visible, click **Add term group** to make it appear.
4. Click **Import** to upload the completed file.

Importing overwrites any terms already entered manually in the same glossary. Review existing terms before importing.

## Assign a guideline

Guidelines can be assigned to agents and AI Assist tasks.

### To an agent

Guidelines are assigned inside the agent configuration. To assign a guideline to an existing agent:

1. Go to **AI Hub > Agents**.
2. Click the pencil icon on the agent card.
3. Under **Guidelines**, select guidelines from the list.
4. Click **Save**.

To assign during initial setup, select guidelines under the **Guidelines** field in the agent configuration flow. See [Set up AI Agents](/docs/hygraph-ai/ai-agents-setup) for the full configuration steps.

### To an AI Assist task

Guidelines can also be assigned when running an AI Assist task. To assign a guideline to an AI Assist task:

1. Open an entry in the content editor.
2. Click **AI Assist** in the top bar.
3. Under **Guidelines**, select guidelines from the list.
4. Configure and run your task as normal.

The selected guidelines apply to that task run only. They are not saved as a default for future AI Assist sessions.

## Manage a guideline

To edit a guideline, click **Edit** on the guideline in **AI Hub > Configurations > Guidelines**. Each guideline category has its own card.

### Markdown-based guideline

Open a Markdown-based guideline (Brand Voice & Tone, Audience & Context, and Legal & Compliance) to edit its name and content, and view its version history:

- **Document**: Edit the guideline name and content.
- **Versions**: View the version history and compare changes between versions. Compare the current version with any previous version. The diff is available in two views:
        - **Split view**: Displays the two versions side by side.
        - **Line by line**: Displays changes inline.

### Glossary

Open a glossary to manage its terms, name, and version history:

- **Terms**: Add, edit, and delete term groups and individual term entries.
- **Settings**: Edit the glossary name.
- **Versions**: View the version history of the glossary. Compare the current version with any previous version. Version restore is not currently available.

## Delete a guideline

You can delete a guideline from the guideline card in **AI Hub > Configurations > Guidelines**. Click the context menu and select <img src="/images/docs/developer-guides/delete.png" class ="inline"></img> (delete icon) next to the guideline you want to remove.

Deleting a guideline removes it from any agents or AI Assist tasks it is assigned to. This action is irreversible.

## Guidelines vs. custom instructions

Agents support two ways to shape output. They serve different purposes and can be used together.

| | Guidelines | Custom instructions |
|---|---|---|
| **Scope** | Project-level<br/>Reusable across agents | Per agent<br/>Not reusable |
| **Purpose** | Persistent context<br/>Brand, audience, legal, vocabulary | One-off output guidance<br/>Length, focus, format |
| **Configured in** | **AI Hub > Configurations > Guidelines** | In agent configuration |
| **Example** | "Direct and conversational. <br/>Technical audience. No corporate filler." | "Summarize in 2–3 sentences." |

Use guidelines for anything that should apply consistently across multiple agents or over time. Use custom instructions for output-specific guidance that applies only to a single agent's task.

## What's next

- [AI Agents](/docs/hygraph-ai/ai-agents): Understand how agents use guidelines at runtime alongside custom instructions.
- [Set up AI Agents](/docs/hygraph-ai/ai-agents-setup): Configure an agent and assign guidelines during setup.
- [Use AI Assist](/docs/hygraph-ai/ai-assist-setup): Use guidelines when running AI Assist tasks in the content editor.
- [Billing](/docs/developer-guides/project/update-billing): Monitor AI token consumption for your project.

---
# AI and Automation

Source: https://hygraph.com/docs/hygraph-ai/index

Hygraph's AI capabilities bring intelligent automation and content generation into your composable content workflows. These features support both **content teams** and **developers**, enabling faster content creation, smarter enrichment, and scalable workflow automation.

This section introduces the three core components of AI in Hygraph.

| Component                     | Primary user        | Purpose                                                                      |
|-------------------------------|---------------------|------------------------------------------------------------------------------|
| **[AI Assist](#ai-assist)**   | Editors             | Generate, improve, and translate content directly in the editor              |
| **[AI Agents](#ai-agents)**   | Editors, Developers | Automate content tasks through manual runs or workflow steps |
| **[MCP Server](#mcp-server)** | Developers          | Connect external AI assistants to your Hygraph project                       |

AI Assist and AI Agents serve complementary purposes: AI Assist is editor-driven and on-demand, while AI Agents can be triggered manually on selected entries or run automatically as part of a configured workflow. The MCP server is independent of both and enables external AI assistants like Claude or Cursor to interact with your project directly.

## AI Assist

**AI Assist** is Hygraph's intelligent content editing assistant, embedded directly in the content editor. It helps editors generate, improve, and translate content within the content entry experience without leaving the editor or requiring developer support.

AI Assist is available out of the box on all Hygraph plans and requires no configuration before use. Editors can start using it immediately on any supported text field.

### Example use cases

- **Content generation** — Draft new product descriptions, blog introductions, or marketing copy based on a short prompt.
- **Content improvement** — Refine existing text for clarity, tone, or readability to ensure consistent quality.
- **Translation** — Translate content into one or more target locales while preserving tone and meaning.

See the [AI Assist overview](/docs/hygraph-ai/ai-assist).

## AI Agents

**AI Agents** automate editorial tasks by running purpose-built agents on your content entries. Agents can be triggered manually from the content table or content entry form, or run automatically when an entry reaches a configured workflow step.
 
Agents are configured in Hygraph without writing code. Each agent is set up once and can be used immediately for manual runs or as part of a workflow.

### Available agents

- **SEO expert**: Generates an SEO report with feedback on how well content is optimized for search, posted as a comment on the entry. Can be triggered manually or through a workflow step.
- **Translator agent**: Translates content into one or more target locales, either triggered manually or automatically through a workflow step.
- **Content summarizer**: Generates short summaries or abstracts and writes the output to a specified target field. Can be triggered manually or through a workflow step.

See the [AI Agents overview](/docs/hygraph-ai/ai-agents).

## MCP Server

The **MCP Server** connects external AI assistants, such as Claude, Cursor, VS Code, and Windsurf, to your Hygraph project using the <Link href="https://modelcontextprotocol.io" target="_blank">Model Context Protocol</Link>. It gives these assistants a direct, permission-aware connection to your project's Content and Management APIs through a standardized interface.

Instead of setting up integrations manually, you describe what you want in plain language and your AI assistant handles it. Tasks like bulk content updates, schema inspection, and cross-environment migrations can be completed with a single prompt.

### Example capabilities

- **Schema inspection** — Ask your AI assistant to describe available content models, fields, and types in your project.
- **Content operations** — Create, read, update, and publish entries via the MCP interface using natural language.
- **Bulk workflows** — Run multi-step operations such as finding all draft entries and updating their priority in a single prompt.

See the [MCP Server overview](/docs/hygraph-ai/mcp-server).

## Where to start

- **Editors**: Start with [AI Assist](/docs/hygraph-ai/ai-assist). It requires no setup and is available immediately in the content editor.
- **Content teams on Enterprise**: Explore [AI Agents](/docs/hygraph-ai/ai-agents) to automate repetitive content tasks like translation, summarization, and SEO review.
- **Developers**: See the [MCP Server overview](/docs/hygraph-ai/mcp-server) to connect your AI assistant of choice to your Hygraph project.

---
# MCP server

Source: https://hygraph.com/docs/hygraph-ai/mcp-server

<Alert theme="info">
  The Hygraph MCP server is available for all projects and is currently in **Early Access**. Features may change, and production use should be evaluated accordingly.
</Alert>

The Hygraph MCP server connects AI assistants to your Hygraph project using the <Link href="https://modelcontextprotocol.io" target="_blank">Model Context Protocol (MCP)</Link>. It gives AI assistants, such as Claude, Cursor, Windsurf, and VS Code, a direct, permission-aware connection to your Hygraph project through a standardized interface to Hygraph's APIs.

Instead of setting up everything manually in Studio, you describe what you want in plain language. Tasks that previously required a developer, such as bulk content updates, schema creation, and cross-environment migrations, can now be done with a single prompt.

## Key benefits

- **Permission-aware by default:** MCP operations follow the permissions defined on your Permanent Auth Token (PAT), so assistants can only perform actions you explicitly allow.
- **Faster workflow automation:** Use natural language to query, create, and publish content or apply structured bulk updates without writing one-off scripts for each task.
- **Standardized integration across clients:** Connect the same Hygraph project to multiple MCP-compatible tools, such as Claude, Cursor, VS Code, Windsurf, using a consistent server interface.
- **Reduced operational risk:** Destructive actions like delete and unpublish are not supported via MCP, helping prevent accidental data loss in automated workflows.
- **Environment-aware workflows:** Use separate endpoints and tokens per environment, such as staging vs production, to support safer deployment and review processes.

## What you can do

### Content operations

With the appropriate permissions (for example, a **General MCP Server** or **Content MCP Server** PAT), AI assistants can:

- Read entries
- Filter and query entries
- Create new entries
- Update existing entries
- Publish entries
- Perform bulk updates
- Move content between environments

### Schema operations

With the correct permissions (for example, a **General MCP Server** or **Management MCP Server** PAT), AI assistants can:

- Inspect existing content models
- Retrieve the structure of a specific model (fields, types, validations)
- Create new content models
- Add new fields to existing models
- Update field configurations
- Manage enumerations and components
- Move schema changes between environments
- Perform structured schema refactoring tasks

## Permissions

All MCP operations are governed by the permissions on your Permanent Auth Token (PAT). Use this table to choose the right token type for your workflow.

| PAT type              | Read | Create | Update | Publish | Schema management | Delete |
|-----------------------|------|--------|--------|---------|-------------------|--------|
| General MCP Server    | ✓    | ✓      | ✓      | ✓       | ✓                 | ✗      |
| Management MCP Server | —    | —      | —      | —       | ✓                 | ✗      |
| Content MCP Server    | ✓    | ✓      | ✓      | ✓       | —                 | ✗      |
| Read-only (custom)    | ✓    | —      | —      | —       | —                 | ✗      |

For full details on creating and configuring tokens, see [MCP server setup](/docs/hygraph-ai/mcp-server-setup#permissions-reference).

## Example prompts

The following example prompts demonstrate how you can use natural language to interact with your Hygraph project through the MCP server.

**Content queries:**
- List all blog posts in Hygraph published this week.
- Find all entries in Hygraph with status `DRAFT` that were last updated more than 90 days ago.

**Content updates:**
- Find all posts in Hygraph with status `DRAFT` and update their priority to `High`.
- Publish all entries in Hygraph currently in review.

**Multi-step workflows:**
- Find all posts in Hygraph with `urgent` in the title, update their priority to `High`, then publish them.
- Move all published entries in Hygraph to the staging environment.

**Schema operations:**
- Show me the structure of the `Product` model in Hygraph.
- Create a new model in Hygraph called `Author` with `name`, `bio`, and `avatar` fields.
- Add a required `SEO Title` field to all models in Hygraph that represent pages.
- Add a new enumeration in Hygraph called `Priority` with values `Low`, `Medium`, `High`.

**Combined workflows:**
- List all blog posts from Hygraph and create individual Markdown files for each post with front matter including slug, title, and publish date.
- Generate TypeScript types for all content models in Hygraph.

## Safety guardrails

The Hygraph MCP server is designed to prevent accidental data loss in automated workflows. The following operations are intentionally not supported via MCP and must be performed manually in Hygraph Studio:

- Delete entries or schema elements
- Unpublish entries

This ensures that AI-assisted workflows cannot unintentionally remove or revert production content or schema.

## Next steps

Ready to connect your AI assistant? See the [MCP server setup guide](/docs/hygraph-ai/mcp-server-setup).


---
# Set up the MCP server

Source: https://hygraph.com/docs/hygraph-ai/mcp-server-setup

<Alert theme="info">
  The Hygraph MCP server is available for all projects and is currently in **Early Access**. Features may change, and production use should be evaluated accordingly.
</Alert>

This guide walks you through connecting an AI assistant to your Hygraph project. For an overview of what the MCP server can do, see [MCP server overview](/docs/hygraph-ai/mcp-server).

## Prerequisites

Before you begin, ensure you have:

| Requirement                | Details                                        |
|----------------------------|------------------------------------------------|
| Node.js                    | `>= 20.18.1` (required for `mcp-remote`)       |
| `npx`                      | Included with Node.js. Verify with `which npx` |
| Hygraph project            | With at least one environment configured       |
| Permanent Auth Token (PAT) | See [Step 1](#step-1-create-a-pat) below      |

## Permissions reference

All MCP operations are governed by the permissions on your Permanent Auth Token (PAT).

To fully leverage the MCP server's functionality, you need the `Read`, `Create`, `Update`, and `Publish` permissions. If you only intend to retrieve content, the `Read` permission is sufficient. For more information on setting up these permissions, see our docs on [Configuring permissions for Permanent Auth Tokens](/docs/getting-started/access-and-permissions/content-api-permissions#set-up-a-pat-with-model-specific-permissions).

| PAT type              | Read | Create | Update | Publish | Schema management | Delete |
|-----------------------|------|--------|--------|---------|-------------------|--------|
| General MCP Server    | ✓    | ✓      | ✓      | ✓       | ✓                 | ✗      |
| Management MCP Server | —    | —      | —      | —       | ✓                 | ✗      |
| Read-only MCP Server  | ✓    | —      | —      | —       | —                 | ✗      |
| Content MCP Server    | ✓    | ✓      | ✓      | ✓       | —                 | ✗      |
| Read-only (custom)    | ✓    | —      | —      | —       | —                 | ✗      |

**Delete operations are never supported via MCP**, for both content and schema. Destructive actions must be performed manually in Hygraph Studio. For more information, see [Safety guardrails](/docs/hygraph-ai/mcp-server#safety-guardrails).

## Step 1 - Create a PAT

Hygraph MCP authenticates using a bearer token. You need to supply the [Permanent Auth Token (PAT)](/docs/api-reference/basics/authorization#permanent-auth-tokens) as the bearer token.

If you haven’t created a PAT yet, follow these steps:

1. In your Hygraph project, go to **Project Settings**.
2. Under **Access**, select **Permanent Auth Tokens**.
3. Click **Generate MCP PAT**.
4. Choose the appropriate permission set (see [Permissions reference](#permissions-reference)), then click **Generate MCP PAT**.
5. Copy the generated token.

If you've previously created a PAT and want to use it for the MCP server, follow these steps:

1. In your Hygraph project, go to **Project Settings**.
2. Under **Access**, click **Permanent Auth Tokens**.
3. Copy the PAT that you want to use to configure the MCP server.

## Step 2 - Get your MCP endpoint

To find the MCP Server API endpoint, follow these steps:

1. In your Hygraph project, go to **Project Settings**.
2. Under **Access**, select **Endpoints**.
3. Under MCP Server API, copy the endpoint.
    ```txt
    https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp
    ```

## Step 3 - Configure your MCP client

Each MCP client handles HTTP servers and authentication differently. 

<Alert theme="warning">
  On Windows, replace `"command": "npx"` with `"command": "npx.cmd"` in all configuration examples below.
</Alert>

Choose your client:

- [Claude Code](#claude-code)
- [Cursor IDE](#cursor-ide)
- [VS Code](#vs-code)
- [Windsurf IDE](#windsurf-ide)
- [Claude Desktop](#claude-desktop)

### Claude Code

Claude Code has native HTTP MCP support with auth headers and does not require `mcp-remote`.

**Recommended:** Use an environment variable.

```bash
export HYGRAPH_TOKEN="your_token_here"

claude mcp add hygraph https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp \
  --transport http \
  --header "Authorization: Bearer ${HYGRAPH_TOKEN}"
```

**Alternative:** Use an inline token.

```bash
claude mcp add hygraph https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_HYGRAPH_TOKEN"
```

**Scope options:**

| Flag             | Effect                      |
|------------------|-----------------------------|
| `--scope local`  | This project only (default) |
| `--scope user`   | All your projects           |
| `--scope global` | System-wide                 |

**Verify the setup:**

```bash
# list configured servers
claude mcp list
claude
> /mcp
# Hygraph should appear in the list
```

If you see errors, run `claude mcp logs hygraph` or see [Troubleshooting](#troubleshooting).

### Cursor IDE

<Alert theme="info">

Cursor's default **Auto** model mode is not compatible with the Hygraph MCP server. You must select a model manually before using MCP tools.

</Alert>

Cursor uses `mcp-remote` to connect to HTTP MCP endpoints.

**Recommended method:** Use the one-click install from Hygraph Studio to install the MCP server in Cursor.

1. In your Hygraph project, go to **Project Settings**.
2. Under **Access**, select **Endpoints**.
3. Under MCP Server API, click **Add to Cursor**.
4. Select the Permanent Auth Token you want to use for the MCP server.
5. Click **Add to Cursor**. When prompted, open Cursor. You are redirected to the MCP server setup page in Cursor.
6. Review the settings and click **Install**. You should see the MCP server listed in the MCP Servers section in Cursor.

**Alternate method:** Install the MCP server manually.

1. In Cursor, navigate to Settings.
2. In the MCP Servers section, click **Add Server** or **Add Custom MCP**.
3. Paste one of the following configurations:
    - **Project-specific configuration:** In the `.cursor/mcp.json` file in your repository

    ```json
    {
      "mcpServers": {
        "hygraph": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
            "--header",
            "Authorization: Bearer YOUR_TOKEN_HERE"
          ]
        }
      }
    }
    ```

    - **Global:** Add to your user-level `~/.cursor/mcp.json` file.

    ```json
    {
      "mcpServers": {
        "hygraph": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
            "--header",
            "Authorization: Bearer ${HYGRAPH_TOKEN}"
          ],
          "env": {
            "HYGRAPH_TOKEN": "your_token_here"
          }
        }
      }
    }
    ```

### VS Code

VS Code has built-in MCP support. Add the following to `.vscode/mcp.json`:

```json
{
  "servers": {
    "hygraph": {
      "url": "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${HYGRAPH_TOKEN}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "HYGRAPH_TOKEN",
      "description": "Hygraph API Token",
      "password": true
    }
  ]
}
```

Alternatively, use `mcp-remote`:

```json
{
  "servers": {
    "hygraph": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
        "--header",
        "Authorization: Bearer ${HYGRAPH_TOKEN}"
      ],
      "env": {
        "HYGRAPH_TOKEN": "your_token_here"
      }
    }
  }
}
```

For more information, see the <Link href="https://code.visualstudio.com/docs/agent-customization/mcp-servers" target="_blank">VS Code MCP docs</Link>.

### Windsurf IDE

1. Go to **Windsurf Settings → Cascade → MCP Servers → Add Server**.
2. In `~/.codeium/windsurf/mcp_config.json`, add:

    ```json
    {
      "mcpServers": {
        "hygraph": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
            "--header",
            "Authorization: Bearer ${HYGRAPH_TOKEN}"
          ],
          "env": {
            "HYGRAPH_TOKEN": "your_token_here"
          }
        }
      }
    }
    ```

3. Click **Refresh Servers**.

### Claude Desktop

1. Open the config file:
    - **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    - **Windows:** `%APPDATA%/Claude/config.json`

    If you can't find the config file, in Claude Desktop, go to **Settings → Developer → Edit Config**.

2. Add the following:

    ```json
    {
      "mcpServers": {
        "hygraph": {
          "command": "npx",
          "args": [
            "mcp-remote@latest",
            "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
            "--header",
            "Authorization: Bearer YOUR_HYGRAPH_TOKEN"
          ]
        }
      }
    }
    ```

3. Quit and reopen Claude Desktop.

<Alert theme="info">
If you manage Node versions with NVM or similar tools, ensure your active Node version is `>= 22` when launching Claude Desktop.
</Alert>

## Multi-environment configuration

For production use, we recommend using separate tokens per environment. The example below uses `mcp-remote`, which is compatible with Cursor, Windsurf, and Claude Desktop. For Claude Code, replace the command/args block with the `--transport http` syntax shown in the Claude Code section above.

```json
{
  "mcpServers": {
    "hygraph-prod": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/master/mcp",
        "--header",
        "Authorization: Bearer ${HYGRAPH_PROD_TOKEN}"
      ],
      "env": {
        "HYGRAPH_PROD_TOKEN": "token_here"
      }
    },
    "hygraph-staging": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/staging/mcp",
        "--header",
        "Authorization: Bearer ${HYGRAPH_STAGING_TOKEN}"
      ],
      "env": {
        "HYGRAPH_STAGING_TOKEN": "token_here"
      }
    }
  }
}
```

## Start using the MCP server

Once your MCP server is running, verify the connection is working by asking your AI assistant a simple question about your project:

- What content models exist in my Hygraph project?
- List the fields on my content models.

If the assistant returns accurate results, your connection is set up correctly. If not, see [Troubleshooting](#troubleshooting).

**First tasks to try:**

- List all entries with status `DRAFT`. This confirms read access is working.
- Create a test entry and publish it. This confirms write and publish permissions are working.
- Show me the structure of my `Product` model, and add a field to it. This confirms schema access is working.

**Verify in Hygraph Studio:**

After trying the tasks above, go to **Hygraph Studio** and check the results directly:

- Open the **Content** section to confirm new or updated entries appear as expected.
- Check the **Schema** section to verify any models or fields that were created.
- Review entry status to confirm published entries are live.

This is a good way to confirm that the AI assistant's actions have taken effect.

**Tips for better results:**

- Be specific about model names and field names. Your AI assistant will use them exactly as given.
- For bulk operations, describe the filter criteria clearly before stating the action. For example: Find all entries tagged `urgent` and update their priority to `High`.
- If a result is unexpected, ask the assistant to explain what query it ran. This helps catch permission or field name issues quickly.

Watch the following video for a practical demonstration of the Hygraph MCP server in action. This video walks through setting up and interacting with the MCP server from Cursor, showing how AI assistants can query content, inspect schema, and perform workflows using natural language.

<VideoEmbed videoId="8730GGrYdng" />

## Security best practices

**Token storage:**
- Use environment variables to store tokens. Do not commit tokens to a remote repository.
- Set up secret management in CI/CD.

**Token permissions:**
- Create role-specific tokens in Hygraph.
- Use read-only tokens for read-only workflows.

**Access control:**
- Configure [Content API permissions](/docs/api-reference/basics/authorization#public-api-permissions) and [Management API permissions](/docs/developer-guides/project/management-api-permissions) in Hygraph.
- Audit token usage regularly.

## Troubleshooting

### 401 Authorization failed

- Verify the token works in the Hygraph API playground.
- Check the token has the correct permissions for the operation (see [Permissions reference](#permissions-reference)).
- Confirm the header format is correct with no extra quotes or spaces: `Authorization: Bearer YOUR_TOKEN`.

### MCP tools not showing or queries failing

If the MCP server connects but you cannot run queries or create entries, required tools might be disabled:

1. In your AI assistant settings, go to **Connectors**.
2. Find the Hygraph MCP connector and click **Configure**.
3. Review tool permissions, and ensure the required tools are enabled. You can set **Allow all tools** for simplicity, or use **Custom** to enable specific tools.

### Server not found

**For Cursor / Windsurf (stdio clients):**

Verify `npx` is available:

```bash
which npx
```

Test `mcp-remote` directly:

```bash
npx -y mcp-remote@latest YOUR_ENDPOINT --header "Authorization: Bearer TOKEN"
```

**For Claude Code:**

```bash
claude mcp get hygraph   # check config
claude mcp logs hygraph  # check logs
```

**For Claude Desktop:**

If you’re using NPM to manage Node versions, make sure you uninstall any NPM versions earlier than 22.

### MCP server tools not displayed

1. Restart your IDE or MCP client.
2. Check the MCP server status in your client's settings.
3. Review server logs.
4. Verify network access to Hygraph endpoint, and permissions associated with the Hygraph token.

### `mcp-remote` connection issues

`mcp-remote` is required for stdio-based clients (Cursor, Windsurf, Claude Desktop) to connect to HTTP endpoints. If you face `mcp-remote` connection issues, you can:

- Update to the latest version: `npm install -g mcp-remote@latest`
- Use the absolute `npx` path in your config (`which npx` to find it).
- Ensure Node.js version is `>= 20.18.1`.

For more, see the <Link href="https://www.npmjs.com/package/mcp-remote" target="_blank"><code>mcp-remote</code> npm page</Link>.

---
# AI tools for editors

Source: https://hygraph.com/docs/editor-guides/ai-tools/ai-tools-for-editors

Hygraph provides AI tools that editors can use directly in the content editor: AI Agents and AI Assist. Both produce output for you to review. Neither tool can publish entries or make changes without your approval.

## AI Agents

Agents run tasks, such as translation, summarization, and SEO analysis, on content entries. An admin configures which agents are available and which models they apply to. As an editor, you trigger agents manually from the content table or content entry form, or they run automatically when an entry moves through a workflow step.

When an agent runs, it writes its output directly to the entry. The entry becomes read-only until you complete the review. Every field the agent changed is shown in a side-by-side diff so you can approve or revert changes field by field.

Hygraph provides three agent types:
 
| Agent | What it does |
|---|---|
| **SEO Expert** | Reviews your entry and posts a structured SEO report as a comment, covering content optimization, heading structure, and metadata gaps. |
| **Translator agent** | Translates content fields into one or more target locales. |
| **Content summarizer** | Generates a concise summary from one or more fields and writes it to a target field. |

See [Trigger agents](/docs/editor-guides/ai-tools/trigger-agents-editors) for the full task steps.

## AI Assist

AI Assist is an on-demand writing tool built into the content editor. You open it on any entry and run one of three tasks on individual fields:

- **Create content**: Generates new content for empty fields based on a prompt.
- **Improve existing content**: Refines existing text for clarity, tone, and readability.
- **Translate content**: Translates existing text into one or more target locales.

AI Assist works on single line text, multi line text, Markdown, and rich text fields. You can run a task on up to five fields at once. All suggestions appear in a review panel before anything is applied to the entry.

See [Use AI Assist](/docs/editor-guides/ai-tools/use-ai-assist-editors) for the full task steps.

## Comparison

| | AI Agents | AI Assist |
|---|---|---|
| **Triggered by** | You (manually) or a workflow step (automatically) | You, on demand |
| **Scope** | One or more entries at a time | Individual fields within a single entry |
| **Tasks** | Translation, summarization, SEO analysis | Create, improve, translate |
| **Review** | Side-by-side diff per field, approve or revert | Suggestion panel, apply or reject |
| **Configured by** | Admin | Available to all editors out of the box |

## AI Guidelines

Guidelines are project-level instructions that give AI tools context about your brand, audience, and terminology. When guidelines are assigned to an agent or applied to an AI Assist task, the output reflects your specific requirements — not just generic AI output.

As an editor, you can read existing guidelines but cannot create or edit them. If agent output doesn't reflect your brand voice, uses the wrong terminology, or ignores compliance requirements, ask your admin to add or update the relevant guideline. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.

## What's next

- [Trigger agents](/docs/editor-guides/ai-tools/trigger-agents-editors): Trigger agents on entries from the Content Table or Content Form.
- [Use AI Assist](/docs/editor-guides/ai-tools/use-ai-assist-editors): Run AI Assist tasks on individual fields within an entry.
- [AI Guidelines](/docs/hygraph-ai/ai-guidelines): Understand what guidelines are and how to request changes from your admin.

---
# Trigger agents

Source: https://hygraph.com/docs/editor-guides/ai-tools/trigger-agents-editors

Agents run tasks, such as translation, summarization, and SEO analysis, on content entries. You can trigger them from the content table (on one or more entries at once) or from the content entry form (on a single entry). When an agent runs, it writes its output directly to the entry. The entry then enters a review state so you can check the changes and approve or revert changes field by field.

For an overview of what agents do and how they work, see [AI Agents](/docs/hygraph-ai/ai-agents).

## Before you begin
 
Hygraph provides three agent types. Your admin configures which ones are available in your project and which models they apply to.
 
| Agent | What it does |
|---|---|
| **SEO Expert** | Reviews your entry and posts a structured SEO report as a comment, covering content optimization, heading structure, and metadata gaps. |
| **Translator agent** | Translates content fields into one or more target locales. |
| **Content summarizer** | Generates a concise summary from one or more fields and writes it to a target field. |

## Trigger an agent

Agents are available on entries in models that an admin has configured for agent use. If you don't see an agent option in the content table or content entry form sidebar, your admin needs to configure the agent for that model.

<Alert theme="info">
  When the Translator agent runs, it overwrites all existing content for the selected locales, including fields that have not changed. Review the localized content after each run to ensure no previously translated fields were unintentionally overwritten.
</Alert>

### Bulk updates in the content table

Use this option to run an agent on multiple entries at once.

1. Go to the **Content** tab and open a view of a content model.
2. Select one or more entries using the checkboxes in the content table.
3. In the action bar at the bottom of the screen, click **Agents** and select the agent you want to run.

The agent runs on all selected entries, up to a maximum of 50 entries per run. The selected content entries become read-only while the agent runs.

### Single entry updates in the content entry form

Use this to run an agent on a single entry you have open.

1. Open the entry in the content editor.
2. In the right sidebar, locate the **Agents** panel.
3. Select the agent you want to run and confirm.

The content entry form becomes read-only immediately while the agent runs.

#### Configure a Content summarizer agent run

When you trigger a Content summarizer, a configuration panel appears before the run starts.

1. Under **Input fields**, select the source fields containing the content to summarize.
2. Under **Entries**, review the content entries whose source fields will be summarized. This field is read-only.
3. Under **Output field**, select the field where the generated summary will be written.
4. Under **Tone**, choose the tone for the generated summary.
5. Confirm to start the run.

For bulk runs from the content table, the same configuration applies to all selected entries.

## What happens during a run

Once triggered, the agent processes the entry and writes its output directly to the relevant fields. While this is happening:

- The content entry form is read-only. No edits can be made to the entry.
- The entry shows a **Pending** status in the content table.

When the run completes, the agent's changes are in place and the entry status changes to **Ready for review**. The entry stays read-only until you complete the review.

If the run does not complete successfully, the entry shows a **Failure** status and the entry content is unchanged.

## Review agent output

The content table shows agent status so you can find entries that need action without opening each one individually.

| Agent status | Description |
|---|---|
| **Pending** | Entries where an agent run is queued or in progress |
| **Ready for review** | Entries where a completed run is awaiting your review |
| **Failure** | Entries where the agent run did not complete successfully |

When an entry shows **Ready for review**, open it to check what the agent changed and approve or revert changes field by field. Each content entry remains read-only until the review is complete.

1. Open the entry. The review screen shows a side-by-side diff: the original content on one side, the agent's output on the other.
2. Review each field the agent changed.
3. Approve changes you want to keep, or revert any you don't.
4. If you revert all fields, the entry returns to its exact pre-agent state.
5. Once you have finished reviewing, the entry exits read-only state and is editable again.

The agent writes to the draft version of your content only. Nothing reaches your published content until you publish the entry.

<Alert theme="warning">
  You cannot edit an entry while a run is in progress or while a completed run is awaiting review. Complete the review to restore edit access.
</Alert>

## Guidelines and agent output

If an agent is assigned guidelines by your admin, its output reflects your project's brand voice, terminology, audience requirements, or compliance constraints. You won't see the guidelines themselves during a run, but their effect shows up in the output.

If the output doesn't match your expectations, ask your admin to review the guidelines assigned to that agent. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.

## Troubleshooting

### Agent option does not appear in the Content Table or sidebar
 
The agent may not be configured for that model. Contact your admin to confirm the agent is set up for **Use in Agent runs** and that your model is included in its scope.
 
### Entry is stuck in read-only state
 
The entry has a completed run awaiting review. Open the entry, complete the review by approving or reverting each field, and the entry will exit read-only state. If you did not trigger the run yourself, another user may have triggered it. Check the **Ready for review** status in the Content Table.

### All selected entries could not be triggered

This can happen for two reasons:

- Every selected entry has an active run in progress or a completed run awaiting review. Complete the pending reviews first, then trigger the agent again.
- A selected entry has an editor currently active on it. Wait until the entries are no longer being edited, then trigger the agent again.
 
### No fields available to select in Content Summarizer configuration panel
 
For **Input fields**, the entry needs at least one supported field with existing content. Confirm the entry has content in the fields you want to summarize.
 
### Output does not match expectations
 
The agent may not have guidelines assigned, or the existing guidelines may need updating. Ask your admin to review the guidelines assigned to that agent. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.

## What's next

- [AI tools for editors](/docs/editor-guides/ai-tools/ai-tools-for-editors): Overview of all AI tools available to editors.
- [Use AI Assist](/docs/editor-guides/ai-tools/use-ai-assist-editors): Run AI Assist tasks on individual fields within an entry.
- [AI Guidelines](/docs/hygraph-ai/ai-guidelines): Understand what guidelines are and how to request changes from your admin.

---
# Use AI Assist

Source: https://hygraph.com/docs/editor-guides/ai-tools/use-ai-assist-editors

AI Assist is an on-demand writing tool built into the content editor. Open it on any entry to generate new content, improve existing text, or translate fields into other locales, without leaving the editor. All suggestions appear in a review panel before anything is applied to the entry.

AI Assist works on single line text, multi line text, Markdown, and rich text fields. You can run a task on up to five fields at once.

## Open AI Assist

1. Open an entry in the content editor.
2. In the top bar, click **AI Assist**. A panel opens showing the available tasks for this entry.

## Choose a task

| Task | Use when |
|---|---|
| **Create content** | Fields are empty and you need to generate content from a prompt. |
| **Improve existing content** | Fields have content you want to refine for clarity, tone, or readability. |
| **Translate content** | Fields have content you want to convert into another locale. | 

## AI Assist tasks

### Create content

Use **Create content** to generate new content for one or more empty fields based on a short prompt. AI Assist produces suggestions based on your prompt and the fields you select. This is useful when creating new entries or filling multiple empty fields at once.

1. Under **Available tasks**, select **Create content**.
2. Under **Fields**, select the fields you want to generate content for. Up to five fields can be selected. Only single line text, multi line text, Markdown, and rich text fields are shown.
3. Under **Locale**, choose the language for the generated content.
4. Under **Guidelines to apply**, select the guidelines you want to apply to the task. If no guidelines appear in the list, none have been set up for your project yet. Ask your admin to add them. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.
5. Optionally, under **Tone of voice**, choose a tone.
6. In the **Prompt** field, describe what you want AI Assist to generate. Include keywords, desired structure, or tone guidance to improve the output.
7. Click **Generate**.
8. Review each suggestion in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.

### Improve existing content

Use **Improve existing content** to refine text for clarity, tone, and readability. AI Assist analyzes the selected fields and suggests enhanced versions while preserving the original meaning. This is useful when reviewing drafts, maintaining consistency across locales, or polishing your content before publishing.

1. Under **Available tasks**, select **Improve existing content**.
2. Under **Fields**, select the fields you want to improve. Only fields with existing content are shown. Up to five fields can be selected.
3. Under **Locale**, choose the language of the content.
4. Under **Guidelines to apply**, select the guidelines you want to apply to the task. If no guidelines appear in the list, none have been set up for your project yet. Ask your admin to add them. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.
5. Optionally, under **Tone of voice**, choose a tone.
6. In the **Prompt** field, describe how you want the content improved. For example: `Simplify complex sentences` or `Make the tone more conversational`.
7. Click **Generate**.
8. Review each suggestion in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.

### Translate content

Use **Translate content** to automatically translate existing text into another locale while preserving tone, structure, and meaning. AI Assist recognizes your project's locale setup and streamlines translations directly in the editor. This is useful to maintain consistent messaging across multiple languages.

1. Under **Available tasks**, select **Translate content**.
2. Under **Fields**, select the fields you want to translate. Only fields with existing content are shown. Up to five fields can be selected.
3. Under **Source locale**, choose the language of the original content.
4. Under **Target locale**, select the language to translate into. You can select more than one locale if your project supports multiple.
5. Under **Guidelines to apply**, select the guidelines you want to apply to the task. If no guidelines appear in the list, none have been set up for your project yet. Ask your admin to add them. See [AI Guidelines](/docs/hygraph-ai/ai-guidelines) for what each category covers.
    - If your project has a Glossary guideline assigned, you can use it here to ensure consistent terminology across locales. 
6. Optionally, under **Tone of voice**, choose a tone.
7. Optionally, in the **Prompt** field, add regional style guidance. For example: `Adapt for British English spelling` or `Use formal register`.
8. Click **Generate**.
9. Review each translation in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.
    - If translated output uses the wrong term for a product name or technical concept, ask your admin to add it to the Glossary guideline.

## Review suggestions

After generating output for any task, AI Assist displays suggestions in the panel before writing anything to the entry.

Review each suggestion in the panel, and either click **Apply** to write the content to the field, or click **Reject** to discard the suggestion.

Once applied, AI Assist edits are saved like any manual update and can be edited at any time.

## Troubleshooting

### No fields appear in the field selector

For **Create content**, the entry needs at least one empty supported field. For **Improve existing content** and **Translate content**, the entry needs at least one supported field with existing content.

### Generated content does not match expectations

Revise your prompt to be more specific. Check the Tone of voice setting. Try selecting fewer fields per run to give AI Assist more focused context. If the output consistently misses your brand voice or terminology, ask your admin to set up guidelines.

### Translation output is inaccurate

Confirm the target locale is enabled in your project. Add regional style guidance in the prompt field. If specific terms are consistently wrong, ask your admin to add them to a Glossary guideline.

### AI Assist tasks are unavailable

Your project may have reached its AI token limit for the billing period. Check with your admin.

## What's next

- [AI tools for editors](/docs/editor-guides/ai-tools/ai-tools-for-editors): Overview of all AI tools available to editors.
- [Trigger agents](/docs/editor-guides/ai-tools/trigger-agents-editors): Trigger agents on entries from the Content Table or Content Form.
- [AI Guidelines](/docs/hygraph-ai/ai-guidelines): Understand what guidelines are and how to request changes from your admin.

---
# Access content

Source: https://hygraph.com/docs/editor-guides/basic-navigation/access-content

Whether you need to edit content you previously created, or you need to do some work on content created by someone else, you will need to access an already created content entry to do this.

## Access content entries

To access already created content:

1. Click on the **Content editor** tab of the app.
2. Find the view where the content is, and click on it.
3. Find the content entry on the table, and click on it to access the edit view.

## Content views

Hygraph offers users a variety of ways to keep their content organized and accessible.

Everyone has different preferences on how content should appear and how clean the UI should be.

There are some simple settings that allow users to customize the look and feel of their content views.

To learn more about the different content views, read our documentation on [the content editor](/docs/editor-guides/content/content-editor#content-views).

## Collaborator view

Our Collaborator view feature displays your own avatar at the top-right corner of the screen as soon as you open a content entry:

![Collaborator view - User's name on hover](/images/docs/user-guides/collaborator-view/collaborator-view-hover-text-you.png)

If someone else opens that same content entry, their avatar will display next to yours.

Hovering over an avatar shows the name of the user:

![Collaborator view - User's name on hover](/images/docs/user-guides/collaborator-view/collaborator-view-hover-text.png)

If more than 3 users are looking at the content entry, the screen will only display two, plus a counter that shows how many more are viewing it.

On hover, the counter will display a card showing the avatars and names of all users currently viewing the content entry:

![Collaborator view - User's name on hover](/images/docs/user-guides/collaborator-view/collaborator-view-hovercard.png)


---
# Access Hygraph

Source: https://hygraph.com/docs/editor-guides/basic-navigation/access-hygraph

## Log in

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/K9qY6gMQxC2pdsO3gfke" caption="Log in to Hygraph" />

To access Hygraph, navigate to <Link href="https://app.hygraph.com/" target="_blank">our app URL</Link>, fill in your credentials and click on **Continue**. Depending on your company, your credentials might be your email address and password, or you can log in using a Facebook, GitHub, or Google account.

After a successful login, you get to the project overview page. The projects you are a member of will display here under **My projects**. Once you locate the project you want to access, click on it. This will display the project homepage, which contains useful widgets, such as last edited schema elements, and access to our documentation and videos.

<Alert theme="warning">

This process might differ depending on your company's security requirements for login and credentials handling.

</Alert>

Would you like to know more? Click here to learn how to [navigate the Hygraph App](/docs/editor-guides/basic-navigation/app-navigation).

## Log out

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/R0T2fteQeqFHL9rd3KQ0" caption="Log out of Hygraph" />

To log out of Hygraph, simply click on your user menu - located on the lower left corner of the screen - then click on `Log out`.

## SSO

<Alert theme="info">

SSO is an enterprise feature, which means not all projects use it.

</Alert>

Single Sign-On (SSO) is an authentication method that simplifies the login process by allowing users to access multiple applications or systems with just one set of login credentials.

Companies often choose to use SSO because it improves security by centralizing user authentication and enabling stronger password policies. Using SSO, companies can implement strong access controls, ensuring that only authorized users can access sensitive information.

As an Editor using Hygraph for your work, SSO allows you to connect via your company domain or mail address.

If your company uses SSO, access <Link href="https://app.hygraph.com/" target="_blank">Hygraph</Link>, enter your work email and click on `Continue`. Hygraph will detect that your company has SSO enabled and will redirect you to your company's SSO.

The specific steps for SSO vary depending on the implementation and the SSO provider chosen by your company. **Please contact your team lead for specific steps on how to log into your company's SSO.**


---
# App navigation

Source: https://hygraph.com/docs/editor-guides/basic-navigation/app-navigation

After successfully [logging in and selecting a project](/docs/editor-guides/basic-navigation/access-hygraph#log-in), you can move to different sections of the app using the tabs in the navigation menu, located on the left of the screen.

## Top bar

![Hygraph - Top bar](/images/docs/editor-guides/basic-navigation/editor-top-bar.png)

| Top Bar section                 | What you can do                                                                                                 |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 1. Project & Environment        | See the current project and environment you are working in. Hover over to view the plan information and use the dropdown to switch projects or environments.  |
| 2. Trial indicator              | View plan details, such as Hobby or 30-day trial. Click here to open the plan picker and upgrade seamlessly within the app.            |
| 3. Command menu                 | Displays a set of actions depending on where you are in Studio.                        |
| 4. Content finder               | Search for content across all entries in your environment.
| 5. Recently viewed              | Check out your recently viewed entries here. |
| 6. AI Assist (Available for enabled projects only) | Helps editors generate, improve, and localize content seamlessly within the content entry experience, without needing to leave the editor.                                      |
| 7. Help                         | Documentation on concepts, code examples, reference apps, features etc, a link to join Hygraph's Slack community.                                                 |
| 8. Contact Support              | Contact our Support teams to resolve any issues you might have.               |
| 9. Notifications                | View system notifications, updates, and alerts related to your project and environment.                        |
| 10. Profile                     | View your account settings and log out of Hygraph Studio.                        |

## App sections

Roles and permissions assigned to users determine what they can see and interact with in the app. The following image shows what the app looks like to a user added to the default Editor system role:

![Hygraph - Default view for Editor role](/images/docs/editor-guides/basic-navigation/editor-role-ui-view.png)

Considering that this view might change depending on your company adding you to a customized Editor role, let's go over all sections available in the app, irrespective of what your role might be:

![Project Homepage](/images/docs/user-guides/project-dashboard.png)

| App section         | What you can do                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 1. Hygraph Studio   | See a list of projects, your apps, and an overview of your projects.                                             |
| 2. Home         | Your project homepage.                                                                                           |
| 3. Schema           | Setup of the content models as required by your project.                                                         |
| 4. Content          | Access existing content, create custom content views, create/ edit content, review content, and publish content. |
| 5. Assets           | Tab to manage and upload your assets.                                                                            |
| 6. API Playground   | An API playground where you can test out API calls.                                                              |
| 7. Apps             | A section to manage apps.                                                                                        |
| 8. Webhooks         | A section to manage webhooks.                                                                                    |
| 9. Project Settings | Details about project information, API access, billing, environments, locales and members                        |

As an Editor, the [Content editor](/docs/editor-guides/content/content-editor) is probably the most relevant section to you, and where you are likely to spend most of your time.

## Command menu

Some schema management tasks require completing a series of similar repeated actions with a lot of confirmation popups. Hygraph Studio allows keyboard navigation through the command menu, which greatly speeds up the process. Open this menu by using `CMD+K` (or `CTRL+K` in Windows), or by clicking `Search` in the top bar:

![Command menu - Search](/images/docs/user-guides/command-menu-navigate.png)

The menu contains the following sections:
- **Schema:** This section offers shortcuts to system and user-defined models, and user-defined components & enumerations in the Schema builder.
- **Content table:** This section offers shortcuts to user-defined models and custom views in the Content editor.
- **Add content:** This section offers shortcuts to create new content entries for any of the models currently in your Schema.
- **Project settings:** This section offers shortcuts to each part of your project settings.
- **Recently viewed:** This section offers shortcuts to the entries you've recently viewed.

![Hygraph - Command menu](/images/docs/editor-guides/basic-navigation/command-menu.png)

## Recently viewed menu

Hygraph offers you a way to quickly go back to a content entry that you recently saw or edited. As a content editor, you usually work in projects with a lot of content views and content entries.

You can access a menu with shortcuts to your recently viewed content entries. Click on the clock icon on the top bar to bring up the recently viewed menu:

![Recently viewed menu access](/images/docs/user-guides/recently-viewed-access.png)

This list:
- Shows up to 30 entries sorted by recency.
- Shows recently viewed or edited entries dating back up to one month.
- Is environment and project specific: It will only include entries from the project & environment that you're currently in.

![Hygraph - Recently viewed menu](/images/docs/editor-guides/basic-navigation/recently-viewed-menu.png)

<Alert theme="info" title="Pro Tip">

- While this menu does not have a search, you can access the [command menu](/docs/editor-guides/basic-navigation/app-navigation#command-menu) and use the search there to find entries in its **Recently viewed** section. Simply press `CMD+K` (or `CTRL+K` in Windows) to bring up the command menu, and type “Recently” in the search for the section to come up.
- If you get an error when trying to access an entry on the list, it may be due to loss of permissions or the entry having been deleted. Contact your supervisor about the permissions.

</Alert>


---
# Project structure

Source: https://hygraph.com/docs/editor-guides/basic-navigation/project-structure

![Hygraph - Schema sample](/images/docs/editor-guides/basic-navigation/schema-sample.png)

Your **schema** is the content structure of your project. It defines all the fields and options that you will work with in the **Content editor**. While as an Editor you won't have to create or modify the schema, you will use it in a way every time you create content.

As project structure is fully customizable, and every company defines their own schema, every schema is different.

<Alert theme="info">

The default Editor role available for all Hygraph projects allows users to see the schema, but they can't edit it in any way.

</Alert>

To access this section of the app, click on the **Schema** option of the navigation menu located on the left of the screen.


---
# Roles & Permissions

Source: https://hygraph.com/docs/editor-guides/basic-navigation/roles-permissions

## Overview

Roles are critical to ensuring the safety of the data stored in a CMS, creating efficient workflows, and building independent teams.

Each role has specific permissions assigned to it, which determine what the user can and can't do in Hygraph, as well as which parts of the app they can and can't see.

For some roles in Hygraph, for instance, developer functionality is hidden to declutter the screen and show only what is relevant to your role.

As an Editor, you won't create roles but will rather be assigned to them. However, it's still useful to know what they are, how they work, and that they could be the reason why your screen may look different from the ones shown in these guides.

## System roles

System roles are the default roles in Hygraph, and cannot be edited or deleted.

There are four standard system roles in Hygraph. As part of the content team, the following roles are relevant to you:

| Role        | Permissions                                             |
| ----------- | ------------------------------------------------------- |
| Admin       | This role access to all of the functionality in Hygraph |
| Editor      | This role can create, update, and delete content        |
| Contributor | This role can create and update content                 |

## Custom roles

![Hygraph - Custom roles](/images/docs/editor-guides/basic-navigation/custom-roles.png)

Since every team is different and has its own structure with its own particular needs, it is possible to create custom roles that match the functionality that a company might need, and only show the parts of the app that the user needs to access.

As an Editor, you will likely not create new roles - which can only be done by users with the role of Owners or Project administrators - but it's important to know that you may have been assigned to a custom role that does not necessarily reflect the permissions discussed in the [System roles section](/docs/editor-guides/basic-navigation/roles-permissions#system-roles).

You can find the **Roles & Permissions** section of the app under **Project settings > Access > Roles & Permissions**.

<Alert theme="info">

The default Editor role available for all Hygraph projects allows users assigned to it to view permissions, but not edit them.

</Alert>


---
# Troubleshooting common issues

Source: https://hygraph.com/docs/editor-guides/basic-navigation/troubleshooting

This document contains a list of frequently reported issues and how to solve them.

## I can't find a content entry

Try using [filters](/docs/editor-guides/content/filter-content) to find the entry you're looking for.

You can use [system filters](/docs/editor-guides/content/filter-content#how-to-use-system-filters) to find content using its stage, ID, date and time of creation, or the username of the editors that crated or worked on it.

## I can't find an asset

You can filter assets using the same [system filters](/docs/editor-guides/content/filter-content#how-to-use-system-filters) that you would use to find a content entry.

## I can't publish my content

Check the content entry for any incomplete fields marked as `Required`. These fields are mandatory and you won't be able to publish the content piece if any of them are incomplete.

![Troubleshooting - Required field](/images/docs/editor-guides/troubleshooting/required-field.png)

If all required fields are complete and you still can't publish, it is possible that you have not been granted proper permissions. Contact your team lead to check.

## I published an entry by mistake

You can [unpublish content entries](/docs/editor-guides/content/publish-content#unpublish-content) if you have the permissions to do so.

## Images not loading in published content

Image assets have stages, just like your content entries. This means that, just like regular content entries, assets can be saved without being published.

When publishing a content entry that contains assets that have not been published, the system prompts you to publish them as well:

![Publish related assets](/images/docs/editor-guides/create-content/publish-related-assets.png)

If you skipped this and your content is not loading correctly, simply go back to the content entry and click on `Publish` again. This time make sure you select and publish all related assets as well.

Make sure you always publish your assets along with your content, to ensure everything loads correctly.

## No projects visible after login

Your invitation to the project might have expired. Let your team lead know that you need a new invitation.

&nbsp;

&nbsp;

---
# Commenting

Source: https://hygraph.com/docs/editor-guides/collaboration/commenting

Commenting is a functionality designed with larger teams containing multiple Editors in mind, to promote work collaboration. You will be able to leave comments in content entries, as well as receive notifications related to the comments.

<VideoEmbed videoId="ilOHGJ4xs6o" />

You can find the comments on the sidebar of a content entry, by clicking on the **Comments** button at the top.

![Comments](/images/docs/user-guides/comments/comments-sidebar.png)

At the top, the sidebar displays how many comments there are in the current content entry, along with a status filter to help you quickly find what you're looking for.

![Comments number & status filter](/images/docs/user-guides/comments/comments-number-status-filter.png)

<Alert theme="success">

When you click on a [notification](/docs/editor-guides/collaboration/notifications), it will take you to the corresponding content entry, where the comment you were notified about will be highlighted.

</Alert>

In the **Comments** sidebar, you can:

- **Leave a new comment:** Write your comment in the text box located at the top of the **Comments** sidebar and click `Add`. You can mention people as well as project roles in your comment by using `@`, which will display a list of users and roles for you to select from. Mentioning people or roles may cause an alert to pop up in their [notifications](/docs/developer-guides/project/commenting#notifications), and/or receive an email depending on their notifications configuration.
  - **Assign a comment:** When you're writing a new comment, you can click `Assign` to assign it to a team member in the project. Upon clicking, a list of users will display and you can simply select one with a click.
- **Use the status filter:** This dropdown menu allows you to sort comments by `All`, `Assigned`,`Open`, and `Resolved`.
- **Reply to a comment:** If you want to reply to a specific comment, you can click **Reply** under it. Once saved, the comment will display as nested within the parent comment. You can click `Reply` to show it, or `Hide` to hide it.
- **Use the context menu:** Use this menu to access the following actions.
  - **Edit:** Clicking on this option allows you to edit the contents of a comment, then click `Update` to save it. You can only edit your own comments while they are open. This option only displays for your own comments.
  - **Resolve / Re-open:** Clicking on this option marks the comment as resolved / re-opened. The people mentioned in the comment will be [notified](/docs/developer-guides/project/commenting#notifications).
  - **Un-assign:** Clicking on this option un-assigns a comment.
  - **Copy link**: Clicking on this option copies the link to the comment. When used, that link will lead to the comment, which will be highlighted in order to be easily found.
  - **Delete:** Clicking on this option deletes the comment. This option only displays for your own comments.

<Alert theme="warning">

The <b>Comments</b> sidebar will only appear in a content entry once it has already been saved for the first time. Before the first save, only the <b>Info</b> sidebar will be available.

</Alert>


---
# Learn about notifications

Source: https://hygraph.com/docs/editor-guides/collaboration/notifications

You can find the **Notifications** menu in the sidebar of your **Hygraph** project, by the bell icon. If you have any unread notifications, you will see a red alert right next to it.

<VideoEmbed videoId="jKk07QdpQrA" />

You receive notifications whenever someone mentions you in a [comment](/docs/editor-guides/collaboration/commenting) or assigns one to you, and when a comment that you have either authored or were mentioned in is resolved or re-opened.

To access these notifications, click on the **Notifications** menu. The Notifications screen offers the following options:

- `Mark as read`: If a comment has not been read, you can mark it as read by clicking the icon on the lower-right corner of the notification.
- `Mark as unread`: If a comment has been read, you can mark it as unread by clicking the icon on the lower-right corner of the notification.
- `Mark all as read`: Use this button at the top-right corner of the notifications screen to mark all notifications as read.
- **Filter notifications:** Use the filters at the top of the Notifications screen to show `All` notifications or only the `Unread` ones.
- **Access a comment:** Click on the notification to navigate to it.
- **Configure notifications:** You can use the configuration menu located at the top of the screen to select if you will to receive notifications in the app, via email, none, or both.

<Alert theme="warning">

Please note that notifications displayed here are from all your projects, not just the project you're currently in.

</Alert>


---
# Learn about conditional fields

Source: https://hygraph.com/docs/editor-guides/content/conditional-fields

During schema creation, field configuration can be set so the field has `Conditional visibility`. This means that it will only display in the content editor when the condition is met.

If you have access to your project schema, you can find out if a field has a condition configured by looking at the `Conditional visibility` checkbox in the configuration screen:

![Conditional field](/images/docs/editor-guides/conditional-fields/conditional-field.png)

The objective of conditional fields is to show only the information you need in the content editor. If you interact with the base field (the field that sets the condition) in a way that fulfils the field's conditional visibility configuration, it will display.

These conditions are applied via using a `Boolean` or `Enumeration` field.

### Boolean field

Using the switch in the content editor to indicate `True` or `False` might fulfil the condition, depending on what condition was configured.

In the following example the condition says that if the `In stock` boolean field is set to `True`, the conditional field will display on the content editor screen:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9wh07htp607vx8mrvloep" caption="Conditional field - Boolean" />

### Enumeration field

Using the enumeration dropdown in the content editor to select one or more options might fulfil the condition, depending on what condition was configured.

In the following example the condition says that if you select `Location 2` from the `Offers` dropdown, the conditional field will display on the content editor screen:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9wh2cjadz07w51uzr8cka" caption="Conditional field - Enumeration" />

---
# The content editor

Source: https://hygraph.com/docs/editor-guides/content/content-editor

## Overview

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/ufvsuoghRpGOTCtFdMVW" caption="Content editor overview" />

The **Content editor** is where you will do most of your work-related activities. To open it, click on the **Content** option located on the navigation menu on the left side of the screen.

This is the app section where content is created, edited, reviewed, updated, published, duplicated and deleted, among other things. The **Content creation** section on the left side menu of this public documentation, basically shows you everything that you can do while working with content.

As soon as you enter the **Content editor** section of the app, you can see the different content views - which you can find below in this document - and the content table for the selected view. You can navigate the content table using the [search](/docs/editor-guides/content/search-content) or by [creating filters](/docs/editor-guides/content/filter-content). You can also [customize the way the form looks](/docs/editor-guides/other-features/configure-columns).

## Content views

Depending on your company's project structure, you may need to work on content across one or more content views.

Hygraph offers users a variety of ways to keep their content organized and accessible. Everyone has different preferences on how content should appear and how clean the UI should be. There are some simple settings that allow users to customize the look and feel of their content views.

Let's go over the different types of content view that you will find in our content editor:

### Default views

![Content editor - default views](/images/docs/editor-guides/create-content/default-views.png)

To start creating content, the first thing you need to do as an Editor is determine where you'll be working. You can find the **Content** menu right by the navigation bar, which contains a list of **Default views**. These views correspond to different sections of the project where you can create content.

The number and names of default views depend on the structure of your project. So, for example, if your project has a section called **Blog post** where you create and store different blog entries, you'll need to select this default view to create a blog post yourself.

### Custom views

![Content editor - custom views](/images/docs/editor-guides/create-content/custom-views.png)

**Custom views** are configurations of a content table that you can save for easy access later. If the default view of your project's content table doesn't work well for you, you can create your own custom view by selecting which columns display on the form and in what order.

[Configuring columns](/docs/editor-guides/other-features/configure-columns) is a great way to declutter your content view by hiding information that is irrelevant to you.

#### Create a custom view

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/4x6zdeYnQnuLTB9xpz7g" caption="Create a custom view" />

1. Navigate to the Content editor and select a model.
2. Create a change to the view by either filtering the content in the search bar at the top, or showing/hiding the columns.
3. Click the `View` dropdown at the top-right of the screen to display the options inside, and select the `Save as new view` option.
4. Provide a `Name` and, optionally, `Description`.
5. Click `Add custom view` to save.

#### Update a custom view

![Update custom view](/images/docs/user-guides/edit-custom-view.png)

1. Navigate to a custom view in the Content editor.
2. Next to the title of the content view, click on the context menu to display the options inside and select `Update custom view`.
3. Apply your changes and click `Update` to save.

#### Delete a custom view

![Delete custom view](/images/docs/user-guides/delete-custom-view.png)

1. Navigate to a custom view in the contextual sidebar of the content tab.
2. Next to the title of the content view, click on the context menu to display the options inside and select `Delete custom view`.
3. Confirm you want to delete.

### App views

![Content editor - app views](/images/docs/editor-guides/create-content/app-views.png)

Sometimes, projects involve using external apps for tasks like translating content. If this is the case, you may find that the app has its own section in the content editor. Look for it under the title **App views** in the **Content** menu.

Keep in mind that the available actions and appearance of **App Views** will depend on the specific app being used. We have [documented](/docs/integrations) several of these apps, and while some of the installation information may not be relevant to your role, these guides can still help you understand how to use each app - including any app-specific views.


---
# Create content

Source: https://hygraph.com/docs/editor-guides/content/create-content

Content creation covers a variety of topics. This document offers a simplified version of this process, while referencing other documents that will extend your knowledge on how to use Hygraph to work with content as an Editor.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/fWfrMGjrTiu5gfouFS4K" caption="Create content overview" />

1. To create content, navigate to the **Content editor** using the right side menu, then select the model you want to create content for. Our [content views](/docs/editor-guides/content/content-editor#content-views) document offers information that can help you find models quickly.
2. Use the `+ Add entry` button on the upper right corner of the screen to create a new content entry. This will display the entry form where you can enter information.

        <Alert theme="info">
        If an admin has started a content freeze, you won't be able to create entries until it's lifted. A banner at the top of Studio tells you when a freeze is active and who set it. See [Content Freeze](/docs/developer-guides/project/content-freeze) for details.
        </Alert>

3. The contents of the form to create an entry depend on the schema configuration for that model. As a result, the form is completely customizable and what you find there will depend on your unique project. Our document on [field types](/docs/editor-guides/content/field-types) explains how to use each field as an Editor to create content.
4. Click on `Save` or `Save & Publish` depending on what your role requires. Consult our documentation on [content publishing](/docs/editor-guides/content/publish-content) for detailed information. You can also [save your content and schedule it for later publication](/docs/editor-guides/content/publish-content#scheduled-publishing).

<Alert theme="info" title="Pro Tip">

You can use [AI assist](/docs/editor-guides/ai-tools/use-ai-assist-editors) to generate content based on a short prompt. AI Assist understands your schema, analyzes the type of field you’re working in, and produces a relevant suggestion that fits the tone and structure of your content. This is useful when creating new entries or filling multiple empty fields at once.

</Alert>


---
# Work with references

Source: https://hygraph.com/docs/editor-guides/content/create-references

Reference fields let you connect content entries to one another directly from the content editor. This page covers everything you need to work with reference fields as an editor.

## Connect an entry

Reference fields appear inline in the content entry form. An empty reference field shows two options: a button to add an existing entry from the referenced model, and a button to create and connect a new one. The button labels include the model name, for example, **Add existing Article** or **Create new Article**.

### Add an existing entry

1. Open the content entry that contains the reference field.
2. Click the **Add existing** button. The label includes the model name, for example, **Add existing Article**.
3. In the **Select** modal, use the search bar or **Filter** to find the entry you want.
4. Select the entry by clicking its row.
5. Click **Add selected entries**.

You can select multiple entries at once if the reference field allows more than one connection.

### Create and connect a new entry

If the entry you want to connect does not exist yet, click the **Create new** button. The label includes the model name, for example, **Create new Article**. This opens a new entry form for the referenced model. Fill in the required fields and save. Hygraph connects the new entry to the reference field automatically. For more information, see [Create a content entry](/docs/editor-guides/content/create-content).

## Remove a connected entry

To remove a connection, open the content entry and locate the reference field. Hover over the connected entry to reveal the context menu, then select **Remove**.

Removing a connection does not delete the referenced entry. It only unlinks it from this field.

If the field has a **Required** validation, removing a connected entry triggers a warning and blocks publishing until you fulfill the validation requirements.

## Sort connected entries

Reference fields that allow multiple connections support drag-and-drop reordering. 

1. Open the content entry that contains the reference field.
2. Locate the reference field in the entry form.
3. Use the six-dot handle on the left of each connected entry to drag and drop it into the order you want.

## One-way and two-way references

How a reference field behaves depends on how your schema developer configured it.

**One-way references** are visible and editable only from the model where the field was added. If a **Post** references an **Author** one-way, you can select an author from the Post entry. Opening an Author entry shows no corresponding field listing connected posts.

**Two-way references** are visible from both sides of the relation. If the same **Post** to **Author** reference is two-way, opening an Author entry shows a field listing all posts connected to it. You can manage the connection from either entry.

If you expect to see a reference field in a model but cannot find it, the reference is likely configured as one-way. Contact your schema developer if you need the field to be visible from both sides.

## Validation warnings

Some reference fields have validation rules set by your schema administrator. Two types of validation can appear:

**Require a connected entry** shows a **Required** tag on the field. If you save or attempt to publish without connecting an entry, Hygraph displays a warning and blocks publishing until the requirement is met.

**Limit connected entry count** applies to fields that accept multiple connections. If you add more entries than the maximum, or fewer than the minimum, a warning appears and blocks publishing.

These validations apply in the UI only. Keep the following in mind:

- An entry that exists as a draft but has not been published still counts as connected.
- If a referenced entry is deleted or disconnected from the other side of a two-way reference, Hygraph removes the link automatically but does not display an error. For example, if an Article requires a linked Product and someone deletes that Product, the Article loses the connection silently. You will only notice the missing link the next time you open the Article.
- These validations are not enforced at the API level. Links can be removed or left empty via the API without triggering any warning.

## Read-only and hidden fields

Reference fields configured as **Read only** are visible in the entry form but cannot be edited. Fields configured as **API only** or **Hidden** do not appear in the content editor at all. If you need to edit a field you cannot see or change, contact your schema administrator.

## What's next

- [Create a content entry](/docs/editor-guides/content/create-content): Learn how to create an entry before connecting it to a reference field.
- [References](/docs/developer-guides/schema/references): Understand how reference fields are configured in the schema.

---
# Create Variants

Source: https://hygraph.com/docs/editor-guides/content/create-variants

Variants allow you to create multiple versions of a main content entry, such as different regional or personalized editions. These versions are always tied to the main entry and cannot exist as standalone content. You can use Variants to tailor specific text, images, or other field values for each audience or locale while keeping all versions organized under the main content entry.

## Create a new Variant

<Alert theme="info" title="Important">

Your developer must enable Variants and add Segments in Hygraph before you can add personalized versions of the main content entry. Share [this document](/docs/developer-guides/schema/variants) with the developer to activate this feature in your project.

</Alert>

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdq97wrs7rbx07uv6cac2c44" caption="Create a new Variant" />

1. Go to the Content Editor, and open your content entry. This is the main content entry.
2. In the right sidebar, under **Variants**, do one of the following:
    - Click **Add**. A new version of the content entry is displayed. The values from the main entry for the default locale are copied into the Variant entry. This makes it easier to make adjustments, especially when the Variant only differs slightly from the main entry.
    - Click **Duplicate**. A new version of the existing Variant is displayed. The values from the Variant for the default locale are copied into the Variant entry. 
3. Only the fields that have Variant support enabled are available for editing. Make changes to the available fields, as required.
    - Turn on the **Show all fields** toggle to view the rest of the fields in the content model in read-only mode. If you want to edit the read-only fields, you need to go back to the main content entry.
4. To add a new locale to the Variant, in the right sidebar, under **Localizations**, click the `+` icon next to the locale. The empty localized fields appear and you can enter the localized text for the Variant in these fields.
4. Now, click **Select segment**.
5. Choose one or more Segments that this Variant applies, and click **Add selected entries**.
6. Click **Save** or **Save & publish**.

<Alert theme="info">

You need to publish the Segment to the same stage as the Variants to see Variants of a certain Segment.

</Alert>

## Modify a Variant

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdqba4k793gq07uvaow9owm5" caption="Modify a Variant" />

After you save a Variant, you can modify the values in different fields of the Variant. You can also modify the Segments that you linked to this Variant.
  - Link more Segments - Select the Segment that you added, and click **Add segment**.
  - Unlink a Segment - Hover over the context menu next to a Segment, and click **Remove**.

## Behavior of Variant fields

Each variant maintains its own values independently. If the same content is needed across entries, you need to manually update it in each entry. When working with variant fields, note the following points:
- Main entry updates: Updating a variant-enabled field in the main entry does not update the same field in its variants.
- Variant Entry updates: Changes made to variant fields do not affect the corresponding fields in the main entry.

Publishing the main entry doesn’t auto-publish its variants. You need to publish each variant separately. To be able to publish a variant, you must have already published the main entry.


---
# Delete content

Source: https://hygraph.com/docs/editor-guides/content/delete-content

## Delete content

There are two ways to delete content. You can do this directly from the form in the content editor, or from inside the content entry itself. This document shows both ways of doing this.

<Alert theme="warning">

Deleting content is an action that can't be undone. Make sure you select the correct content entry for deletion to prevent content loss.

</Alert>

### From the from

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/SqEK9KiSoyDADEONOJ8m" caption="Delete content from table view" />

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Locate the content entry you want to delete and click on its checkbox to select it.
4. Click on the `Delete` icon that displays at the top of the content table.
5. Confirm deletion to finalize the process.

### From inside the content entry

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/a0gqrqMYRNWW6EbJKxwh" caption="Delete content from entry view" />

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Locate the content entry you want to delete and click on the pencil icon to enter the content-editing mode.
4. Click on the 3 dots context menu at the top of the screen next to the content entry name, which displays a menu, and click on the `Delete` option.
5. Confirm deletion to finalize the process.

## Bulk delete

You can select several content pieces from the content table and delete them at the same time.

![Bulk delete](/images/docs/editor-guides/create-content/bulk-delete.png)

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Use the checkboxes to select the content entries you want to bulk delete.
4. Click on the `Delete` option at the top of the table.
5. A confirmation screen will display informing you that this action cannot be rolled back. Click on `Delete entries` to confirm and finalize the process.


---
# Duplicate content

Source: https://hygraph.com/docs/editor-guides/content/duplicate-content

## Duplicate content entries

Editors can sometimes duplicate a content entry as a way to speed up content creation. You can find this option inside each content entry.

Follow these steps to duplicate content:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/URdxjYG7SsqCrln9RS66" caption="Duplicate a content entry" />

1. Click on the content editor tab of the app.
2. Find the view where the content is, and click on it.
3. Find the content entry on the table, and click on it to edit.
4. Click on the duplicate icon at the top of the screen.
5. The duplicated entry loads. The word **(copy)** at the end of the title line indicates that you're currently in a copy of the original entry. You can now make the necessary changes to the content entry.
6. Click on `Save` or `Save & publish` depending on your workflow. If you try to leave without saving, the system will warn you.

<Alert theme="warning">

Note that if the content entry contains reference fields, some of the relations will be duplicated and others won't. The system will notify you if this is the case.

The system will not duplicate references with the cardinality **one to one**.

What is copied in this case is the reference - the link between the two content pieces - but not the referenced entry itself. To duplicate referenced entries within an original entry, check out the following section of this document.

Please carefully examine duplicated content containing references to prevent errors. You may need to reference content manually in duplicated entries.

</Alert>

## Duplicate relations

When working with relations - also known as [references](/docs/editor-guides/content/field-types#references) - you can quickly duplicate referenced entries within an original entry. This is a quick way to keep the format of the related content, while allowing you to make content edits that won't affect other entries that contain the same reference.

![Duplicating related content](/images/docs/user-guides/duplicating-related-content.png)

1. Navigate to the content entry that contains the relation you want to duplicate.
2. Click on the context menu and select `Duplicate`.
3. The duplicated reference screen will display. Here you can make the necessary edits, then click `Save` or `Save & Publish` depending on your workflow.
4. Click on the `X` at the top-left corner of the editor to return to the original content entry you were working on. The reference field now contains the duplicated reference.

    <Alert theme="warning">
    System behavior depends on field configuration:

    - If the field allows referencing only one model, the duplicate will replace the original.

    - If the field allows referencing more than one model, the duplicate will display as an additional reference.
    </Alert>


---
# Edit content

Source: https://hygraph.com/docs/editor-guides/content/edit-content

Whether you need to edit content you previously created, or you need to do some work on content created by someone else, you will need to access an already created content entry to do this.

## Edit a content piece

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/U6JAunVFQVa8v2RewLlw" caption="Edit a content entry" />

To access already created content:

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Find the content entry on the form, and click on the pencil icon to edit.

      <Alert theme="info">
      If an admin has started a content freeze, you won't be able to edit entries until it's lifted. A banner at the top of Studio tells you when a freeze is active and who set it. See [Content Freeze](/docs/developer-guides/project/content-freeze) for details.
      </Alert>

4. Make all the changes you need to make.
5. Click on `Save` or `Save & Publish`, depending on what your role requires. Our documentation on [content publishing](/docs/editor-guides/content/publish-content) offers detailed information about this. You can also [save your content and schedule it for later publication](/docs/editor-guides/content/publish-content#scheduled-publishing).

<Alert theme="info" title="Pro Tip">

You can use [AI assist](/docs/editor-guides/ai-tools/use-ai-assist-editors) to improve existing content based on a short prompt. AI Assist understands your schema, analyzes the type of field you’re working in, and produces a relevant suggestion that fits the tone and structure of your content. This is useful when reviewing drafts, maintaining consistency across locales, or polishing your content before publishing.

</Alert>

---
# Field types in the content editor

Source: https://hygraph.com/docs/editor-guides/content/field-types

The contents of the form to create an entry depend on the schema configuration for that model. This document aims at assisting you in the [content creation process](/docs/editor-guides/content/create-content), and explains how to use each field type as an Editor to create content.

<Alert title="Pro tip" theme="info">

Field names are customizable, this means that these fields might appear in your project under a name of your company's choosing. For practical purposes, you will find them named after the field type here.

For example, your project might have an asset picker field that allows selecting multiple assets listed as "Image carousel" in the content entry you're working with.

If you have trouble identifying a field type, ask your team lead for help. Once you know the field type, you can refer to our guide for working with that type.

</Alert>

## Single line text

![Single line text](/images/docs/editor-guides/create-content/single-line-text.png)

Single line text fields often serve as titles or subtitles. The name of the field will often indicate what they are for, and you can simply add the information by typing it in.

## Multi line text

![Multi line text](/images/docs/editor-guides/create-content/multi-line-text.png)

Multi line text fields can accommodate text in multiple lines, and often serve as description fields. The name of the field will often indicate what it is for, and you can simply add the information by typing it in.

## Markdown

![Markdown](/images/docs/editor-guides/create-content/markdown.png)

Markdown is a popular markup language that you can use to add formatting elements to text.

Markdown fields can accommodate markdown text in multiple lines, and often serve as description fields.

The name of the field will often indicate what it is for, and you can simply add the information by typing it in. This field has a number of options for Editors writing content. Let's go over them:

- `Write`: Select this option to write content.
- `Preview`: Select this option to preview what your markdown content will look like published.
- `H`: Heading. Select this option to make your line of text into a heading or subheading within the text. This option adds `###` to your Markdown field, but consider that in markdown each `#` represents a heading level. So, you could use `#` to represent a first level title, then `##` to represent a second level subtitle within that section. You can edit this manually in your Markdown field.
- `B`: Bold. Select the text you want to make bold and then click on this button. To get the same effect manually, add `**` before and after your text, like this `**<your_text>**`.
- _`I`_: Italic. Select the text you want to italicize and then click on this button. To get the same effect manually, add `*` before and after your text, like this `*<your_text>*`.
- ~`S`~: Strikethrough. Select the text you want to strike through and then click on this button. To get the same effect manually, add `*` before and after your text, like this `~<your_text>~`.
- `Links`: Select the text you want to add a link to and then click on the link icon. This will add the link syntax to your text, making it look like this`[<your_text>]()`. Add the URL you want the text to link to between the brackets, like this `[<your_text>](https://www.your_link.com)`.
- `Quotes`: Select the text you want to format as quoted, then click on the quotes icon. To get the same effect manually, add `>` before your text.
- `Inline code`: Select the text you want to format as inline code, then click on the inline code icon. To get the same effect manually, add **\`** before and after your text.
- `Image`: To add an image, click on the image icon to display the asset selection screen. Use the options on this screen to [upload a new asset or select an existing one](/docs/editor-guides/other-features/asset-manager). The image added to your markdown field will have the following format `![your_image.jpeg](https://www.your_image_url.com)`. You can also add images manually using this syntax.
- `Bulleted list`: To format items as a bulleted list, select the text and then click on the bulleted list icon. You can also click on the icon, then write the list item, but you must do so for every line. To get the same effect manually, add `-` before each line of text.
- `Numbered list`: To format items as a numbered list, select the text and then click on the numbered list icon. You can also click on the icon, then write the list item, but you must do so for every line. To get the same effect manually, add `1.`, `2.`, `3.` and so on before each line of text.
- `Checklist`: To format items as a checklist, select the text and then click on the checklist icon. You can also click on the icon, then write the checklist item, but you must do so for every line. To get the same effect manually, add `- []` to the text, like this `- [<your_text>]`.

You can learn more about Markdown <Link href="https://www.markdownguide.org/getting-started/" target="_blank">here</Link>.

## Slug

![Slug](/images/docs/editor-guides/create-content/slug.png)

The slug field is a URL friendly identifier. If your schema configuration determines that the slug generates from a template, it will autocomplete. If not, you can write it yourself.

A usual format to follow for the slug is to use the same text as your title line in lowercase, and with `-` instead of spaces.

## Rich text

![Rich Text editor](/images/docs/user-guides/rte/rte-ui-buttons.png)

This field is a text editor with formatting included in all Hygraph projects. It provides great flexibility when it comes to creating, editing, and manipulating content entries that include text and images.

If your project schema is configured so that your model has a `Rich Text` field, you'll see it like the image shown above in the content editor. Let's go over what you can do with it:

1. `Text format`: This dropdown allows you to format text you've highlighted in the text area. You can format it as normal text as well as different heading levels.
2. Typography options:
    - `Bold`: Use this typography option you to make text bold.
    - `Italic`: Use this typography option you to italicize the text.
    - `Underline`: Use this typography option you to underline the text.
3. `Link`: Use this option to add a link.
4. `Block quote`: Use this option to format the text as a block quote.
5. `Code`: Use this option to format the text as inline code.
6. `Asset`: This option allows you to include an asset.
7. Lists:
    - `Bulleted list`: Use these options to create a bulleted list.
    - `Numbered list`: Use these options to create a numbered list.
8. `Code block`: Use this option to format the text as a code block.
9. `Iframe`: An inline frame - or iframe - is an `HTML` element that loads another `HTML` page into the current document. Click on this button to displays a popup where you can enter an iframe URL (the URL of the HTML page you wish to insert in the current document). After you've entered a valid iframe URL, click on the `OK` button to add it to your content.
10. `Class`: Classes in this context are styles that are coded in the `CSS` of your front end. If your project uses this, you will be informed what the class names are. Simply highlight the text and click on the `Class` button. Use this option to assign classes to your text. A popup will display for you to type in the `Class name`, then click on `Ok` to finalize the process.
11. `Table`: Use this option to add a table. Once the table is added, if you click on it and go back to the same button, it will now read `Edit table` and will offer the following options:
    - `Remove Table`: Use this button to remove the selected table.
    - `Toggle Headers`: Use this button to make the first line into table headers. You can undo this by clicking on `Toggle Headers` again.
    - `Insert Columns`: Use this button to insert a column. It will be inserted to the right of the cell your cursor is on.
    - `Remove Columns`: Use this button to remove a column. It will remove the column your cursor is on.
    - `Insert Row`: Use this button to add a row to your table. It will be added below the row your cursor is on.
    - `Remove Row`: Use this button to remove a row from your table. It will remove the row your cursor is on.
12. `Subscript`: Use this option to format text as subscript.
13. `Superscript`: Use this option to format text as superscript.
14. `Enter fullscreen`: If the workspace seems too small, you can use this option to enter the fullscreen rich text editor mode. You can exit this mode by clicking on the `Exit fullscreen` button.
15. `Embed`: If embeds have been configured for the Rich Text field in your project's schema, this option allows you to embed content from a model. Think of it as adding content entries within this content entry. The models that you can embed content from depend on the schema configuration for this field.

### Links

To add a link to your content entry while using the Rich Text field, click on the `Link` button to display the **Insert link** popup. This popup contains two tabs: **Settings** and **Attributes**.

#### Settings

![RTE - Insert link - Settings tab](/images/docs/user-guides/rte/rte-links-settings.png)

- **Link type:** Use the radio buttons to select one of the two options. Your selection modifies the fields that show on screen.
  - **URL:** Select this option to add a link to an external source, that is, a link outside of your Hygraph project.
  - **Entry:** Select this option to add a link to an existing entry in your Hygraph project.
- **Link text:** You can add text for your link in this field. If you are creating a `URL` link type and don't complete this field, the **Link address** will be used as **Link text**. This field becomes required for the `Entry` link type. If you selected text before clicking on the link button, this field will be autopopulated with the selected text.
- **Link address:** Required field where you can type the URL you want to link to. This field only displays for the `URL` link type.
- **Open link in new tab:** Use this checkbox for your link to open in a new tab in the browser. This field only displays for the `URL` link type.
- **Link title:** Optional field where you can enter text that will display when hovering over the link. This field only displays for the `URL` link type.
- **Select entry:** Click on `Add existing entry` to select the entry in your Hygraph project that you want to create a link to. Only models that can be embedded will display in the dropdown. This field only displays for the `Entry` link type.
- **Action buttons:**
  - **Cancel:** Click on this button to cancel the process.
  - **Insert:** Click on this button to save the link and add it to your content entry.

#### Attributes

You can optionally complete the following `HTML` attributes:

![RTE - Insert link - Attributes tab](/images/docs/user-guides/rte/rte-links-attributes.png)

- **Rel attribute:** This attribute defines the relationship between the current document and the linked resource.
- **Class attribute:** This attribute specifies one or more `classnames` for an element. You can add classes separated with spaces here.
- **ID attribute:** This attribute is used to specify a unique `id` for an `HTML` element.
- **Action buttons:**
  - **Cancel:** Click on this button to cancel the process.
  - **Insert:** Click on this button to save the link and add it to your content entry.

### Assets

Clicking on the `Assets` button opens the **Select Asset** screen:

![RTE - Select assets](/images/docs/user-guides/rte/rte-assets-select.png)

You will normally use this option to add images to your rich text.

Select an asset from the available assets list by clicking on the purple reference icon located at the beginning of each asset entry. This will automatically add the asset to your content.

If the asset you need has not yet been uploaded to your project, you can do so from this screen as well by clicking on the `Upload` button. To do this, simply click on `Upload` and follow our [Upload asset](/docs/editor-guides/other-features/asset-manager#upload-asset) step-by-step guide from step 2 onwards.

### Embeds

If your project has been configured to enable embeds in rich text, use this option to create **inline** and/or **block embeds**.

<Alert theme="warning">

Only the content from the selected models in the Rich Text field schema configuration is available to be embedded.

</Alert>

#### Inline embeds

**Inline embeds** give Content Creators maximum flexibility to add references or relations directly within the text so they can move faster. This also clears up clutter around content creation, so they are able to add things like authors, citations, product attributes and more without having to add extra fields within the content entry.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/fot3mXZRZWEJDJugFvt3" caption="Rich text inline embeds" />

The example video above shows how to use inline embeds to add an author to your rich text.

To select an entry and add it to your content, simply click on the purple reference icon that you can find to the left of each content entry.

The editor displays this embed as a dropdown. If you click on it, you will find the options to `Edit` or `Remove` it.

#### Block embeds

**Block embeds** give Content Creators more flexibility with less clutter. Use block embeds to insert assets and other content entries inside the text as a block. This can be useful when adding images like logos, or referencing audiences to previous created material that support the new content item like blog posts, documents, announcements, etc.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/nwWQFbnSO2sF5nRpNXOZ" caption="Rich text block embeds" />

The example video above shows how to use block embeds to add a content entry from a different model to your rich text. In this case it is a blog post being referenced in the current content.

To select an entry and add it to your content, simply click on the purple reference icon that you can find to the left of each content entry.

The editor displays this embed as a block, which has a three dots context menu on right. If you click on it, you will find the options to `Edit` or `Remove` the embed.

## Number

![Number](/images/docs/editor-guides/create-content/number.png)

You can only enter numbers in this field. You can do so manually, or using the **up / down** arrows that display to the right of the field when you click on it.

This field is normally used for information such as IDs and quantities.

## Float

![Float](/images/docs/editor-guides/create-content/float.png)

Floats are commonly used for calculations. You can type in numbers that can have up to three decimals. You can enter the numbers manually, or using the **up / down** arrows that display to the right of the field when you click on it.

This field is normally used for information such as ratings and prices.

## Boolean

![Boolean](/images/docs/editor-guides/create-content/boolean.png)

A boolean field only allows two values: `true` and `false`.

What `true` and `false` represent, depends on what this field is used for in your project.

## Date

![Date](/images/docs/editor-guides/create-content/date.png)

This field is a calendar picker. Click on the field to select a date from the calendar.

![Calendar picker](/images/docs/editor-guides/create-content/date-picker.png)

## Date and time

![Date and time](/images/docs/editor-guides/create-content/date-time.png)

This field is a calendar picker where you can also enter a time. Click to select a date, then click the time field to enter the hour and minutes manually.

![Date and time picker](/images/docs/editor-guides/create-content/date-time-picker.png)

## JSON editor

![JSON editor](/images/docs/editor-guides/create-content/json-editor.png)

This field is not normally used by Editors, but it's useful to know that it supports JSON syntax (JavaScript Object Notation), and is often used for storing large amounts of data from other systems.

## Asset picker

![Asset picker](/images/docs/editor-guides/create-content/asset-picker.png)

You will normally use this option to add images to your content entries. Note that assets can be other file types as well, such as documents. You might have to add different assets to your project depending on the type of content your create, but regardless of the file type, the **Assets** screen works in the same way.

The `+ Create & add new <field_name>` button follows the [Add asset entry flow](/docs/editor-guides/other-features/asset-manager#add-asset-entry), then returns you to the current screen, where you'll see your new asset added to the entry.

The `+ Add <field_name>` button works as follows:

![Select assets](/images/docs/user-guides/rte/rte-assets-select.png)

Depending on assets configuration in your project, you will be able to select one or more assets. If configuration allows selection of a single asset, you can select an asset from the available assets list by clicking on the purple reference icon located at the beginning of each asset entry. This will automatically add the asset to your content.

If configuration allows selecting more than one asset, you can use the available checkboxes to select the assets you want instead, and then click on `Add selected assets`.

If the asset you need has not yet been uploaded to your project, you can do so from this screen as well by clicking on the `Upload` button. To do this, simply click on `Upload` and follow our [Upload asset](/docs/editor-guides/other-features/asset-manager#upload-asset) step-by-step guide from step 2 onwards.

## Color

![Color](/images/docs/editor-guides/create-content/color-picker.png)

You can use the color picker field to select a color. Click on it to display the color selection palette.

![Color picker displayed](/images/docs/editor-guides/create-content/color-picker-displayed.png)

To select the color, you can either click on it directly on the palette, type in the **Hex** color code, or the **RGB** color code. You can also control color opacity typing a value in the **A** field. **A** set to 100 is a solid color with no transparency.

## Map

![Map](/images/docs/editor-guides/create-content/map.png)

The map field is a Google Maps tool that lets you select geo coordinates on a world map.

This field offers the following controls:

- `Map`: Use this button to display a map view.
- `Satellite`: Use this button to display a satellite view.
- `Fullscreen`: Use this button to display the map on fullscreen mode. Click on `esc` on your keyboard to exit fullscreen mode.
- `+`: Use this button to zoom in.
- `-`: Use this button to zoom out.
- `Search for location`: Use this text field to enter a location name, then click on the `Search` button to initiate the search. Your search results will display on the map.

If you're using a laptop with a trackpad, you can also use it to zoom in / out, and to navigate the map.

## Enum dropdown field

![Dropdown field](/images/docs/editor-guides/create-content/dropdown.png)

An enumeration dropdown field lets you select an option from a list of items, which has previously been configured in the schema as an enumeration.

Simply click on it and select one of the options.

## Taxonomies

![Dropdown field](/images/docs/editor-guides/create-content/taxonomy.png)

A taxonomy dropdown field lets you select an option from a list of hierarchical items, which has previously been configured in the schema as a taxonomy. Use this to classify content using the structure of the taxonomy.

Simply click on it and select one of the options.

## Components

A component is a predefined set of fields that can be used across project models and content entries. Hygraph offers two types of component fields:

- `Basic component field`: A simple collection of fields that you can embed in your content entry.
- `Modular component field`: A dynamic collection of fields, in the sense that it might contain several components, which you as an Editor will be able to select from when working on a content entry. Selecting a component embeds its fields in a content entry.

<Alert title="Pro Tip" theme="info">

Components may contain all the other types of fields in this document. When inside a component, a field works the same way as when it is outside of a component.

You can find out the field types, look them up in this guide, and follow the instructions on how to work with them.

- [Here's an example on how to work on a basic component](/docs/editor-guides/content/field-types#basic-component-example)
- [Here's an example on how to work on a modular component](/docs/editor-guides/content/field-types#modular-component-example)

</Alert>

You can use **Basic components** for content that will remain the same in all entries.

**Modular components** are often used for blocks, where a content entry can take many shapes and therefore needs to be dynamic. This way you as an Editor will be working with a more compact content entry template, and simply select the component or components you need for that specific content entry.

Components internal field combinations depend on project configuration. As each project is unique, this document only covers the basic workings of components.

### Basic component

![Basic component field](/images/docs/editor-guides/create-content/basic-component.png)

To start working on the contents of a basic component field, click on the `+Add <component_name>` link. This embeds the fields that make up that basic component in your content entry so you can start working on them.

#### Basic component example

The following example uses a basic component to add a banner to a blog post:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/WaH0DlrhR7yXlULPhJyj" caption="Basic component field example" />

As an Editor working on our example, you need to click on `+ Add entry` in the **Content editor** to create a new blog post. After adding a `title` and a `slug`, click on the banner component, which in this case is a basic component.

Because it is a basic component, the button simply says `+ Add Banner`. After clicking on it, you can start working on the fields that make up this component.

<Alert title="Pro Tip" theme="info">

Remember that components are a reusable collection of fields, and that fields inside components work just like fields outside of them.

You have all the information on how to work with each field type in this document, you just need to identify them. For instance, the `Caption` shown in this example is a single line text field.

</Alert>

### Modular component

![Modular component field](/images/docs/editor-guides/create-content/modular-component.png)

To start working on the contents of a modular component field, click on the `+Add component` link to display the components menu.

![Modular component field displayed](/images/docs/editor-guides/create-content/modular-component-displayed.png)

Clicking on a component from the menu embeds the fields that it contains in your content entry so you can start working on them.

If the project configuration allows multiple values, you will be able to add more than one component to a content entry. To do so, click on the `+ Add another component` link at the bottom of the section to display the selection menu again.

![Add another component](/images/docs/editor-guides/create-content/modular-component-addanother.png)

If you're working with a modular components fields and have added several components to your content entry, you can reorganizing them by using the arrows that display on each line when you select multiple components.

![Organize components](/images/docs/editor-guides/create-content/modular-component-organize.png)

Each component on the list has a three dots context menu, which displays the following options when you click on it:

![Modular components context menu](/images/docs/editor-guides/create-content/modular-component-contextmenu.png)

- `Move to bottom`: Use this option to move the current component to the bottom of the list.
- `Remove <component_name>`: Use this option to remove the current component from the list.
- `Add component above`: Use this option to add a component above the current one. Scrolling over this option displays a list of components. Select one by clicking on it.
- `Add component below`: Use this option to add a component below the current one. Scrolling over this option displays a list of components. Select one by clicking on it.

#### Modular component example

The following example uses a modular component to add a video section to a blog post:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/mfJNyzRvQvCRXT2BjDrj" caption="Modular component field example" />

As an Editor working on our example, you need to click on `+ Add entry` in the **Content editor** to create a new blog post. After adding a `title` and a `slug`, move onto the component section, which in this case is a modular component.

Because it is a modular component, Clicking on `+ Add component` displays the selection of components that you can choose from. After selecting the `Video section` option, you can start working on the fields that make up this component.

<Alert title="Pro Tip" theme="info">

Remember that components are a reusable collection of fields, and that fields inside components work just like fields outside of them.

You have all the information on how to work with each field type in this document, you just need to identify them. For instance, the `Thumbnail` shown in this example is an asset picker field.

</Alert>

## References

In content entries you may find references - also called relations - that connect to one model, or more. The behavior of the field will be slightly different depending on this:

![References](/images/docs/editor-guides/create-content/references.png)

The above example shows both. If you click on `Add existing (...)` or `Create & add new (...)` on a reference that connects to multiple models, a menu displays where you can select which model, as you can see on the image. Clicking on an option displays either the selection or creation screen for the entries of that model.

Instead, if you click on `Add existing <model_name>` or on `Create & add new <model_name>` on a reference that connects to only one model, the selection or creation screen for that model will display directly.

Independently from how many models a reference might connect to, configuration might also make it possible to select one or more entries. There is a detailed explanation of this below, but basically:

- References may connect to one model or more.
- Configuration may allow you to select only one entry from the connected model, or more.

Also, please consider:

- `Add existing`:
  - The way to add an entry, as well as the options shown on screen afterwards are different for references that allow selecting [only one entry](/docs/editor-guides/content/field-types#single-entry), versus references that allow selecting [multiple entries](/docs/editor-guides/content/field-types#multiple-entries).
- `Create and add new`:
  - The options shown on screen after creating & adding an entry are different for references that allow selecting [only one entry](/docs/editor-guides/content/field-types#single-entry), versus references that allow selecting [multiple entries](/docs/editor-guides/content/field-types#multiple-entries).
  - This is a regular [content creation](/docs/editor-guides/content/create-content) screen, which may contain different [field types](/docs/editor-guides/content/field-types) depending on model configuration. The created entry is added to the references upon saving.

### Single entry

<Alert title="Pro tip" theme="info">

If you're creating & adding rather than just adding an entry, skip over to the screen options, below the entry selection flow.

</Alert>

![Select a reference](/images/docs/editor-guides/create-content/reference-select.png)

Click on the reference icon to select a reference. Clicking on the icon closes the screen and displays the reference on the list:

![Reference selected](/images/docs/editor-guides/create-content/reference-single-entry-displayed.png)

Your options:

- `Replace <model_name>`: Use this to change your entry selection. This opens the selection screen again, where you can repeat the process with a different entry.
- `Create & replace <model_name>`: Use this to create a new entry and replace the current one with it. This does not delete the previously created entry.
- `Clear`: Use this to remove the selected entry.
- 3 dots context menu:
  - `Edit`: Edits the related entry, not the entry selection. Edition here follows the standard [editing flow](/docs/editor-guides/content/edit-content).
  - `Duplicate`: Duplicates the related entry. You will need to save before moving on. The system then takes you to the duplicated content entry automatically. There, you can make all necessary changes before saving and/or publishing. Check out our [Duplicate relations](/docs/editor-guides/content/duplicate-content#duplicate-relations) document for more information on this.
  - `Remove`: Removes the related entry from the screen.

### Multiple entries

<Alert title="Pro tip" theme="info">

If you're creating & adding rather than just adding an entry, skip over to the screen options, below the entry selection flow.

</Alert>

![References - select multiple entries](/images/docs/editor-guides/create-content/reference-select-multiple.png)

Use the checkboxes to select one or more entries, then click on `Add selected <model_name>` at the bottom of the screen. he entries you selected will display on the references list.

![References - multiple](/images/docs/editor-guides/create-content/reference-multiple.png)

Your options:

- `Add existing documents`: Use this to open the selection screen again to add more documents.
- `Create & add more documents`: Use this to create a new document and add it to this list.
- 3 dots context menu:
  - `Edit`: Edits the related entry, not the entry selection. Edition here follows the standard [editing flow](/docs/editor-guides/content/edit-content).
  - `Duplicate`: Duplicates the related entry. You will need to save before moving on. The system then takes you to the duplicated content entry automatically. There, you can make all necessary changes before saving and/or publishing. Check out our [Duplicate relations](/docs/editor-guides/content/duplicate-content#duplicate-relations) document for more information on this.
  - `Move to top`: Moves the related entry to the top of the list. This option does not display if you're using the context menu on the item that is already at the top of the list.
  - `Move to bottom`: Moves the related entry to the bottom of the list. This option does not display if you're using the context menu on the item that is already at the bottom of the list.
  - `Remove`: Removes the related entry from the screen.
  - `Add entry above`: Allows adding an entry above the current one. Clicking on this displays two action links on top of the current entry, giving you the option to add an existing entry or creating and adding a new one.
  - `Add entry below`: Allows adding an entry below the current one. Clicking on this displays two action links below the current entry, giving you the option to add an existing entry or creating and adding a new one.


---
# Filter content

Source: https://hygraph.com/docs/editor-guides/content/filter-content

## Overview

Filtering allows you to use specific parameters to restrict the entries that display in a content table. This is helpful when trying to create a more curated overview of content.

These filters can be useful when building content views, looking for a specific type of content, or finding content that matches several parameters.

![Filters](/images/docs/editor-guides/filter-content/filters.png)

## Quick Filters

Our **Quick Filters** feature reduces the time and effort required to create a filter. You can now find the content you need, faster.

![Quick Filters](/images/docs/editor-guides/filter-content/quick-filters.png)

It offers several predefined filters that apply instantly when selected, allowing you to focus on you work without unnecessary distractions.

<Alert theme="info" title="Pro Tip">

You can apply Quick Filters to both regular content views and asset views.

</Alert>

**To add Quick Filters**, simply use the `Filter` menu to display the available options and select one.

![Add a Quick Filter](/images/docs/editor-guides/filter-content/add-quick-filters.png)

Once you select a Quick Filter, the regular filter appears in the filter bar and the content table shows the sorted content.

You can apply more than one Quick Filter. To do this, simply use the filter menu again and select another one.

For instance, the following image shows a content table where two Quick Filters have been applied, `Created by me` & `Only published entries`:

![Quick Filter applied](/images/docs/editor-guides/filter-content/quick-filter-applied.png)

## Column filters

The `Filters` menu also contains column filters.

![Column filters](/images/docs/editor-guides/filter-content/column-filters.png)

Column filters allow you to filter content by some system and custom fields, stage and ID.

Quick and column filters function in the same way. [The following document section](/docs/editor-guides/content/filter-content#adjust-filters-manually) explains how to use them.

## Adjust filters manually

You can find the filters on any content view, at the top of the content table. Clicking on the `Filters` menu displays your options for quick and column filters:

![Filters menu](/images/docs/editor-guides/filter-content/filters-menu.png)

You can use the `Search` at the top of the filters menu to quickly find a filter.

To filter content, select one of the fields listed for filtering. It can be a quick or column filter:
- **If you selected a quick filter**, the results will show on the table below.
- **If you selected a column filter**, you need to configure it:
        - Select a condition. [This document section explains what each condition does](/docs/editor-guides/content/filter-content#general-filter-conditions).
        - Enter a comparison value in the input to the right of the filter method.

<Alert theme="warning">
At the moment, you can't use these filters for components, union type references, or Rich Text.
</Alert>

**To remove a filter**, simply click the `X` button next to it.

## How to use system filters

### Stage

![Filter content by stage](/images/docs/editor-guides/filter-content/filter-by-stage.png)

1. Click `Filter` to open the filter menu.
2. Select `Stage` from the column filters list.
3. Use the dropdown menu next to `Stage` to pick a [condition](/docs/editor-guides/content/filter-content#general-filter-conditions).
4. Select a stage from the second dropdown menu.

For example, if you select `is` on the first dropdown, and then `PUBLISHED` on the second, the filter will show you all the content entries that are currently on the `PUBLISHED` stage.

It is not necessary to type in a keyword in the search field for this filter to work, so you can use the filter on its own to return search results on all the content in that model, or you can use it to narrow down a search that uses keywords.

### ID

An ID is a unique identifier of your content entry that the system assigns to it when you first save it. You can see it on the sidebar in the edit view, under **Entry information**.

![Content entry ID](/images/docs/editor-guides/filter-content/id-in-content-entry.png)

If you know the ID of a content entry you are looking for - totally or partially - you can use that to quickly find it using the `ID` filter.

![Filter content by ID](/images/docs/editor-guides/filter-content/filter-by-id.png)

1. Click `Filter` to open the filter menu.
2. Select `ID` from the column filters list.
3. Use the dropdown menu next to `ID` to pick a [condition](/docs/editor-guides/content/filter-content#string).
4. Enter a value in the text field next to the conditions dropdown.

**Some examples**

Imagine we are looking for a content entry with the ID `clgm2kql0bspm0burfoqjqhdl`:

- If you know the exact ID, you could simply use `is clgm2kql0bspm0burfoqjqhdl` as a filter. This would return only one result, the exact content entry you're looking for.
- If you know the the ID starts with `clgm`, you could use `starts with cglm` as a filter. This would return all content entries that have IDs that start with `cglm`.
- If you know the ID ends in `qhdl`, you could use `ends with qhdl` as a filter. This would return all content entries that have IDs that end with `qhdl`.

### Created / Updated at

The `Created at` and `Updated at` filter look at `DateTime` fields in the content entry. This can be the date of creation/update, as well as any **DateTime** field in the schema configuration for the model.

![Filter content by Created at](/images/docs/editor-guides/filter-content/filter-by-createdat.png)

<Alert theme="warning">

The `DateTime` field contains date/time information at UTC, which would look something like this `2007-12-03T10:15:30Z`. Since this information is extremely exact, it is best to use the Created at filter with the `less than` or `greater than` conditions.

</Alert>

1. Click `Filter` to open the filter menu.
2. Select `Created at`, or `Updated at` from the column filters list.
3. Use the dropdown menu to pick a [condition](/docs/editor-guides/content/filter-content#datetime).
4. Enter a value in the calendar field next to the conditions dropdown.

### Created / Updated / Published by

These filters take a list of project users, and compare a value you provide to relational fields in the project, so - in a way - this would be filtering by relations.

![Filter content by Created by](/images/docs/editor-guides/filter-content/filter-by-createdby.png)

This filter functions like so:

1. Click `Filter` to open the filter menu.
2. Select `Created by`, `Updated by`, or `Published by` from the column filters list.
3. Use the first dropdown menu to pick a condition, and the second one to enter or select a value. These are reference filters, and you can find detailed information about their usage [here](/docs/editor-guides/content/filter-content#reference).

## Filters and your schema

While all projects have the default system filters, different filters may display depending on your project schema configuration.

Let's go over this with an example. Look at the following project schema for a **Product** model:

![Filters example: The Schema](/images/docs/editor-guides/filter-content/filters-example-schema.png)

It has fields for product name, slug, image, sections, description, price, a condition, an enumeration for product size, and a taxonomy for product category.

When you go to the **Content editor** section of the app, select the **Product** view, and click on the `Filter` menu, you will see most of the fields you saw in the schema as filters under "Column Filters", in addition to the system filters that are always there.

![Filters example: The Content Editor](/images/docs/editor-guides/filter-content/filters-example-contenteditor.png)

Some fields, such as rich text, can't be filtered in the content editor and require a different approach through the API Playground which, in turn, requires familiarity with `GraphQL`, and is not usually Editor work.

## General filter conditions

In general, a filter will provide different conditions depending on the type of field configured in the schema. You will find string, boolean, enums, taxonomy, reference, and DateTime.

Each type offers different conditions to filter by:

#### String

Strings are sequences of characters, so they are often used for text fields such as titles or descriptions. They offer the following conditions for filtering:

- `is`: This condition filters for content that matches the text you enter.
- `is not`: This condition filters for content that doesn't match the text you enter.
- `contains`: This condition filters for content that contains the text you enter.
- `doesn't contain`: This condition filters for content that doesn't contain the text you enter.
- `starts with`: This condition filters for content that starts with the text you enter.
- `doesn't start with`: This condition filters for content that doesn't start with the text you enter.
- `ends with`: This condition filters for content that ends with the text you enter.
- `doesn't end with`: This condition filters for content that doesn't end with the text you enter.

An good example of this type of filter that you can find in all projects is the [ID filter](/docs/editor-guides/content/filter-content#id).

#### Boolean

Boolean fields can take two values: `true` and `false`. In all cases, booleans provide a condition dropdown, and then a second dropdown containing the `true` / `false` values.

The conditions dropdown menu for booleans contains the following options:

- `is`: This condition filters for content that matches the value you select from the dropdown.
- `is not`: This condition filters for content that doesn't match the value you select from the dropdown.
- `is null`: This condition filters for content where no value has been assigned to the field. You do not need to select any value for this filter.
- `is not null`: This condition filters for content where a value has been assigned to the field. You do not need to select any value for this filter.

**For example**, imagine you have a boolean for `reviewed`. Like all booleans, it can only take two values: `true` & `false`. So, if you set the filter to `reviewed is true`, the filter will return all entries where the `reviewed` boolean field has been set to true.

#### Enum

Enums are lists of items. Your project has them as system fields, like in the case of content stage, and may also have them as custom dropdown fields in the schema.

In all cases, enums provide a condition dropdown, and then a second dropdown containing the values configured on the list for that enum. Like this:

![Taxonomy - example](/images/docs/editor-guides/filter-content/filter-enum.png)

The above example shows a filter where the enum is a list for product sizes. This particular field allows multiple values, so you have checkboxes next to every option in case you need to select more than one.

The conditions dropdown menu for enums contains the following options:

- `is`: This condition displays content that is an exact match for the value you select from the dropdown.
- `is not`: This condition displays content that is not an exact match for the value you select from the dropdown.
- `is null`: This condition displays content where no value has been assigned to the field. You do not need to select any value for this filter.
- `is not null`: This condition displays content where a value has been assigned to the field. You do not need to select any value for this filter.
- `includes all`: This condition displays content that matches all the values you select from the dropdown.
- `includes none`: This condition displays content that matches none of the values you select from the dropdown.
- `includes some`: This condition displays content that matches some of the values you select from the dropdown.

Please note that not all enums will display all the options above, some may display them partially. An example of this is the [Stage filter](/docs/editor-guides/content/filter-content#stage).

#### Taxonomy

A taxonomy is a group of terms arranged in a hierarchical structure. Your project has them as system fields and may also have them as custom dropdown fields in the schema.

In all cases, taxonomies provide a condition dropdown, and then a second dropdown containing the values configured for that taxonomy. Like this:

![Taxonomy - example](/images/docs/editor-guides/filter-content/filter-taxonomy.png)

The above example shows a filter where the taxonomy is a category for product types.

The conditions dropdown menu for taxonomies contains the following options:

- `is`: This condition displays content that is an exact match for the taxonomy node you select from the dropdown.
- `is not`: This condition displays content that is not an exact match for the taxonomy node you select from the dropdown.
- `is in`: This condition displays all content that matches the multiple taxonomy nodes you select from the dropdown.
- `is not in`: This condition displays all content that does not match the multiple taxonomy nodes you select from the dropdown.
- `descendants of`: This condition displays content that matches the selected taxonomy node and all nodes below it.

#### Reference

![Filtering by relations](/images/docs/user-guides/relational-filter.png)

Filtering by reference is basically filtering by relation. This filter is dynamic, in the sense that it changes depending on the relational field you select, but in general terms its usage follows three steps:

1. Select the field of this model that you want to use.
2. Select a condition from the dropdown menu.
3. Some conditions will require that you type in some data to filter by, such as a name or a slug. `Updated At` and `Created At` require that you select a date from a calendar and type in a time. `Is null` and `Is not null` do not require any additional input.

<Alert theme="warning">
**It is not possible to filter by union-type reference fields** - those that allow you to reference more than one model in a field.
</Alert>

The references you can select for your filter depend on project configuration. All projects have the default reference filters - we'll look into them in a moment - but they can also have a number of custom ones.

The default reference filters that all projects have are [`Created by`, `Updated by`, and `Published by`](/docs/editor-guides/content/filter-content#created-updated-published-by). They are related to project users and provide the following relational fields that you can select from the dropdown:

- `IsActive`: IsActive checks if the user is an active member of the project. This is a [boolean field](/docs/editor-guides/content/filter-content#boolean) and, as such, it offers all conditions a boolean field does, and you can select `true` or `false` from the values menu.
    - `true`: The user is still in the project (a current member, or an active permanent auth token / app token).
    - `false`: The user has been removed or deactivated. Their name may still appear on older entries (for example, as “deactivated” in comments), but they no longer have access to the project.
- `Kind:` Kind is an [enum field](/docs/editor-guides/content/filter-content#enum) that checks if the creator of a piece of content is a user or a token. As most enum fields, it offers all conditions an enum field does, and you can select one of the following values from the values menu:
  - `MEMBER`: The content was created / updated by a user.
  - `PAT`: The content was created / updated by a token.
  - `PUBLIC`: The content was created / updated by the public API.
  - `WEBHOOK`: The content was created / updated by a webhook.
  - `APP_TOKEN`: The content was created / updated by an app.
- `Picture`: This checks for pictures of the related users. This is a [string field](/docs/editor-guides/content/filter-content#string) and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.
- `Name`: This checks for names of the related users. This is a [string field](/docs/editor-guides/content/filter-content#string) and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.
- `Updated At`: This checks for date and time of update of a content entry. This is a [DateTime field](/docs/editor-guides/content/filter-content#datetime) and, as such, it offers all conditions a DateTime field does, and allows you to select a date and time from a calendar picker.
- `Created At`: This checks for date and time of creation of a content entry. This is a [DateTime field](/docs/editor-guides/content/filter-content#datetime) and, as such, it offers all conditions a DateTime field does, and allows you to select a date and time from a calendar picker.
- `ID`: This checks user IDs. This is a [string field](/docs/editor-guides/content/filter-content#string) and, as such, it offers all conditions a string field does, and allows you to enter text to apply that condition to.

#### DateTime

The `DateTime` field contains date/time information at UTC, which would look something like this `2007-12-03T10:15:30Z`.

This field type offers the following conditions:

- `is`: This condition returns exact matches to the date and time selected, including milliseconds. Considering this filter won't provide results unless the information provided is exact, it is recommended to stick to `less than` and `greater than` conditions for date & time.
- `is null`: If your project has custom fields for date & time, and these fields are not required, then they may not always have a value assigned to them. If this is the case, using the `is null` filter returns all content entries where that custom date & time field does not have a value.
- `is not null`: This condition returns all content entries that have a value assigned to a date and time field.
- `is not`: This condition returns all entries where the date & time is not the one you provide.
- `less than`: This condition returns all entries where the date & time is earlier than the one you provide.
- `less than or equal to`: This condition returns all entries where the date & time is earlier than or equal to the one you provide.
- `greater than`: This condition returns all entries where the date & time is later than the one you provide.
- `greater than or equal to`: This condition returns all entries where the date & time is later than or equal to the one you provide.

An example of this that you can find in every project are the [`Created at` and `Updated at` filters](/docs/editor-guides/content/filter-content#created-updated-at).


---
# Localize content

Source: https://hygraph.com/docs/editor-guides/content/localize-content

## Overview

As an Editor, you might need to create content in different languages. Localization is supported as a core feature in Hygraph. A locale is a language you add for the content to be translated into. You will see them as spaces in your content entry where you can add a translation.

While as an Editor you don't have to configure any settings for localization, it's important to know that the languages available for you to use in the content editor depend on the project configuration. These locales can be both default and custom.

When configuring the schema, a field can be set as `Localized field`. This means each field can have an assigned localization which is part of field configuration, and not a duplication of that content. This basically means that you can work on localized content entries with "per field" granularity.

## Add a localization

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/glcUk1yQBu2p1M6mK9gA" caption="Add a localization" />

1. Navigate to the content editor tab.
2. Select the view where you want to create a content entry.
3. Click on `+ Add entry` in the upper right corner of the screen.
4. Add a locale by clicking on the `+` icon next to it. You can find the locales on the right sidebar.
5. Work on your entry.
6. Enter the localized text in the localized fields and complete the rest of your entry according to your task.
7. Select `Save` or `Save & Publish` depending on your workflow.

<Alert theme="info" title="Pro Tip">

You can use [AI assist](/docs/editor-guides/ai-tools/use-ai-assist-editors) to automatically translate existing text into another locale while preserving tone, structure, and meaning. AI Assist recognizes your project’s locale setup and helps streamline localization workflows, making it easy to maintain consistent messaging across multiple languages.

</Alert>

## Show or hide a locale

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/9wst3gsjRxqUs28YtvSN" caption="Show or hide a locale" />

To work with localizations, look for the eye icon in the localization section of the content entry sidebar.

- If the eye is closed, that means the locale is hidden.
- If the eye is open, that means the locale is shown.

Click on the eye icon to toggle between shown and hidden.

Selecting and deselecting locales controls their visibility on the screen. If a locale already has content saved in it, selecting or deselecting it will not affect the content, only its visibility.


---
# Publish content

Source: https://hygraph.com/docs/editor-guides/content/publish-content

## Overview

When you create content, publishing it is crucial to make it visible and available to others. Only content that is published can be consumed by others.

Hygraph has two [Content Stages](/docs/editor-guides/other-features/content-stages), `DRAFT` and `PUBLISHED` - with `PUBLISHED` being the only stage where content is visible to others and ready to be consumed.

Once you've finished working on a content piece in the `DRAFT` stage, simply click `Save & Publish` or `Publish` to move it to the `PUBLISHED` stage.

Content entries often contain [assets](/docs/editor-guides/content/field-types#asset-picker) and [references](/docs/editor-guides/content/field-types#references), so it's a good practice to make sure they are also `PUBLISHED`. This ensures everything loads properly.

![Publish related assets](/images/docs/editor-guides/create-content/publish-related-assets.png)

If any assets or references are still in the `DRAFT` stage, you'll be prompted to publish them when you click `Save & Publish`. When content is `PUBLISHED`, the system creates a new [version](/docs/editor-guides/other-features/content-versions) that shows how the content has evolved and when it was last updated.

## Publish a content entry

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/aTorsufoS2OmLZeMmgzh" caption="Publish a content entry" />

To publish an already created content entry:

1. Navigate to the Content editor tab of your Hygraph project.
2. Select the content model where the entry you want is.
3. Click on the pencil icon of the content entry you want, to enter the content-editing mode.
4. Click on the `Publish` button on the upper right corner of the screen to publish.

Please note that if you make any changes to the content entry, the `Publish` button will say `Save & Publish` instead.

<Alert theme="info">
If an admin has started a content freeze, you won't be able to publish entries until it's lifted. A banner at the top of Studio tells you when a freeze is active and who set it. See [Content Freeze](/docs/developer-guides/project/content-freeze) for details.
</Alert>

## Bulk publishing

You can select several content pieces from the content table and publish them at the same time.

![Bulk publishing](/images/docs/editor-guides/create-content/bulk-publishing.png)

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Use the checkboxes to select the content entries you want to bulk publish.
4. Click on the `Publish` option at the top of the table.
5. A confirmation screen will display. Click on `Publish` again to finalize the process.

## Scheduled publishing

![Scheduled publishing](/images/docs/editor-guides/create-content/schedule-option-inmenu.png)

Hygraph gives you the possibility to schedule the publishing and unpublishing of content pieces.

When editing a content entry, instead of publishing right away, you can choose the option `Schedule Item` for publishing at a later day and time:

1. Inside a content entry, click on the arrow icon on the `Publish` button to display the dropdown menu. Remember that if the content piece has never been saved before, the button says `Save & Publish`.
2. Click `Schedule` to select a later date and time. If the content piece has never been saved before, the option you need to select is `Save & Schedule`.
3. Select whether you want to [schedule the entry individually](/docs/editor-guides/content/publish-content#schedule-entry-only), if you want to [add it to an existing release](/docs/editor-guides/content/publish-content#add-to-an-existing-release), or if you want to create a new release for it, then click `Continue`.

The next screen depends on what you selected on step 3:

### Schedule entry only

You can publish (or unpublish) individual content entries at a specified date and time by selecting the `Schedule entry only` option.

![Schedule Item](/images/docs/user-guides/schedule-item.png)

On this screen you must provide the scheduling information:

- `Action`: You can schedule content to be **published** or **unpublished**. Click on the radio buttons to select one of these options.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

- `Date & Time`: Use the calendar picker to select a date and a time for the scheduled action.
- `Timezone`: Use the dropdown menu to select a time zone.
- **Locales:** Use the checkboxes to select which localizations should be included. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.
- **Optional:** If there are any unpublished assets or references linked to the entry you are scheduling, you can schedule those as well. Use the checkboxes to select the items you want to schedule.

![Schedule Related Entries](/images/docs/user-guides/schedule-relations.png)

Finally, click `Schedule` to proceed. A success message will display on the lower right corner of the screen to confirm that you have successfully scheduled the entry.

### Add to an existing release

You can bundle multiple content entries into a single release that will be published (or unpublished) at a specified date and time.

Your releases will be shown if you choose to **Add item to a release**:

![Schedule release](/images/docs/user-guides/schedule-release.png)

If your project has [scheduled releases](/docs/editor-guides/other-features/content-releases) configured, you can simply add your content entry to it:

1. `Release`: Use the dropdown menu to select a release.
2. `Action`: Use the radio buttons to select `PUBLISH` or `UNPUBLISH`.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

3. `Date & Time`: Use the calendar picker to select a date and a time for the scheduled action. Alternatively, you can manually type in the date in the format that's visible in the placeholder of the field.
4. `Timezone`: Use the dropdown menu to select a time zone.
5. **Locales:** Use the checkboxes to select which localizations should be included. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.
6. **Optional:** If there are any unpublished assets or references linked to the entry you are scheduling, you can schedule those as well. Use the checkboxes to select the items you want to schedule.
7. Click on `Schedule` to finalize the process.

<Alert theme="warning">

If you select this option and your project has no schedules configured, the system will let you know that you need to add one first.

</Alert>

### Add to a new release

You can create a new release to add the current entry to by selecting `Add to a new release`:

![Schedule release](/images/docs/user-guides/add-to-new-release.png)

1. Give the new release a `Name` and, optionally, a `Description`.
2. `Action`: Use the radio buttons to select `PUBLISH` or `UNPUBLISH`.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

3. **Locales:** Use the checkboxes to select which localizations should be included. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.
4. **Optional:** If there are any unpublished assets or references linked to the entry you are scheduling, you can schedule those as well. After clicking on `Continue` in the previous screen, a new screen will display where you can select the items. Use the checkboxes to select the items you want to schedule.
5. Click on `Schedule` to finalize the process.
![Schedule Related Entries](/images/docs/user-guides/schedule-relations.png)

### Scheduled entries in the content table

Scheduled entries in the content table display a stage pill with a clock on it:

![Scheduled entries in the content table](/images/docs/user-guides/scheduled-entries-pill.png)

Hovering over the pill will show you schedule publishing information for that entry.

![Scheduled entries in the content table](/images/docs/user-guides/scheduled-entries-pill-hover.png)

## Bulk scheduling

You can select several content pieces from the content table and schedule them for publishing at the same time.

![Bulk scheduling](/images/docs/editor-guides/create-content/bulk-scheduling.png)

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Use the checkboxes to select the content entries you want to bulk schedule.
4. Click on the `Schedule` option at the bottom of the table.
5. Here you have three options:
    - If you want to schedule the entries without adding them to a release, [follow this workflow](/docs/editor-guides/content/publish-content#schedule-entry-only).
    - If you want to add the entries to an existing release, [follow this workflow](/docs/editor-guides/content/publish-content#add-to-an-existing-release).
    - If you want to add the entries to a new release, [follow this workflow](/docs/editor-guides/content/publish-content#add-to-a-new-release).

## Unpublish content

You can use this workflow to unpublish one or more content entries.

![Unpublish content](/images/docs/editor-guides/create-content/unpublish-content.png)

1. Click on the content editor tab of the app.
2. Locate the view where the content is, and click on it.
3. Use the checkboxes to select one or more content entries to unpublish.
4. Click on the `Unpublish` option at the bottom of the table.
5. A confirmation screen will display. Click on `Unpublish` again to finalize the process. The content entries will go back to the `DRAFT` stage. Check out our document on [content stages](/docs/editor-guides/other-features/content-stages) to learn more about the meaning of stages.


---
# Review content

Source: https://hygraph.com/docs/editor-guides/content/review-content

If your specific role as an Editor involves reviewing content created by others, then you need to access already created content and potentially make modifications to it.

To access created content and enter the content-editing mode, please check out our [Edit content](/docs/editor-guides/content/edit-content) document.

As a reviewer, you may be required to publish the content once reviewed, or to leave it ready for publication. After making the necessary changes to the content entry:

- Click on `Save` to save without publishing.
- Click on `Save & Publish` to do both. Our documentation on [content publishing](/docs/editor-guides/content/publish-content) offers detailed information about this.
- You can also [save your content and schedule it for later publication](/docs/editor-guides/content/publish-content#scheduled-publishing).

<Alert theme="info">
If an admin has started a content freeze, you won't be able to save or publish entries or assets until it's lifted. A banner at the top of Studio tells you when a freeze is active and who set it. See [Content Freeze](/docs/developer-guides/project/content-freeze) for details.
</Alert>

---
# Search content

Source: https://hygraph.com/docs/editor-guides/content/search-content

The most common feature for navigating the content editor is using the **Search** function, which enables you to quickly find any entries that match the keywords you enter. Users are able to search for any keyword used in the content entry, such as `Author`, `Title` or `Content Keywords`.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/j8rAGPdfTeywGTncnufO" caption="Search in content editor" />

To search for a content entry:

1. Navigate to the content editor and find the view that contains the content entry you want to search for.
2. Click on the search field and type in the keyword or keywords. You can optionally use the dropdown menu to select a localization.

You can narrow down your search using [search filters](/docs/editor-guides/content/filter-content).

<Alert theme="warning">

Note that Hygraph does not support full text search at the moment, which means searching through `Rich Text` or `JSON` is currently not possible.

</Alert>


---
# Update content

Source: https://hygraph.com/docs/editor-guides/content/update-content

## Outdated content

Hygraph lets you know which pieces of content are outdated compared to the published version. They display in the content editor with a blue `Published` tag, like so:

![Publish content](/images/docs/editor-guides/update-content/publish-outdated.png)

Content entries where the published version is the same as the latest version of the content entry saved in the system, display a green `Published` tag in the `Stages` column of the form.

## Update content

Sometimes you need to update a piece of content that you or or another user created previously. To do so, you simply need to follow the [content edition flow](/docs/editor-guides/content/edit-content).

If your role involves publishing other editor's content so that the published version is the same as the latest version in the system, you can [filter content entries by stage](/docs/editor-guides/content/filter-content#stage) to find the content entries that are published but outdated - that is, in the blue `Published` stage - and easily access them.

    <Alert theme="info">
    If an admin has started a content freeze, you won't be able to update entries until it's lifted. A banner at the top of Studio tells you when a freeze is active and who set it. See [Content Freeze](/docs/developer-guides/project/content-freeze) for details.
</Alert>



---
# Editor Guides

Source: https://hygraph.com/docs/editor-guides/index

Our Editor guides offer information on how to use Hygraph to create content and collaborate with other people on your team.

These documents outline the basic navigation and key functions performed under the Editor role in Hygraph, including reviewing, editing, and publishing content to the site.

A Headless CMS differs from a traditional CMS in a variety of ways. The term headless comes from the idea of removing the “Head” or front end from the “Body” of the back end. Headless CMSs are essentially a content repository that make it accessible via API to any platform. Headless CMSs are inherently more flexible than traditional CMSs because since there is no assumption that a team is building a website, teams are able to build all sorts of products, from apps, to Alexa Skills, to LED Displays, or multiple of these at once.

Headless CMSs empower content teams to quickly create, modify, and upload content to their chosen project without the need of the development teams. Dev teams set up the project structure, called the schema, and content teams are able to take over and add content without needing Devs to make any further changes.

Headless CMSs speed up development of new projects and opens up a new realm of possibilities for creating new products or elements quickly.

## Section contents

This section offers a contents map to help you readily find what you're looking for.

### Basic navigation

This section contains documents that will help you easily navigate the Hygraph App.

| Document                                                                      | Contents                                                                                                                                                                                          |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Access Hygraph](/docs/editor-guides/basic-navigation/access-hygraph)         | This document contains information on how to log in and out of Hygraph.                                                                                                                           |
| [App navigation](/docs/editor-guides/basic-navigation/app-navigation)         | This document contains information on the different sections of the hygraph app. Please note that as an Editor you may not be able to see all sections, as this depends on project configuration. |
| [Roles & permissions](/docs/editor-guides/basic-navigation/roles-permissions) | This document contains information on system roles and custom roles.                                                                                                                              |
| [Project structure](/docs/editor-guides/basic-navigation/project-structure)   | This document contains information on what the Schema is and how this will impact your work.                                                                                                      |
| [Troubleshooting](/docs/editor-guides/basic-navigation/troubleshooting)       | his document contains a list of frequently reported issues and how to solve them.                                                                                                                 |

### Content creation

This section covers all aspects of content creation that may be relevant to an Editor.

| Document                                                             | Contents                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [The content editor](/docs/editor-guides/content/content-editor)     | This document contains information on Hygraph's content editor, default and custom content views, as well as app views.                                                                                                                                                |
| [Create content](/docs/editor-guides/content/create-content)         | This document contains a simplified step-by-step tutorial on content creation.                                                                                                                                                                                         |
| [Edit content](/docs/editor-guides/content/edit-content)             | This document contains a step-by-step guide on how to access and edit already created content.                                                                                                                                                                         |
| [Review content](/docs/editor-guides/content/review-content)         | This document contains information on the steps you need to follow if your role implies reviewing others' work.                                                                                                                                                        |
| [Update content](/docs/editor-guides/content/update-content)         | This document contains information on outdated content and how to update it.                                                                                                                                                                                           |
| [Search content](/docs/editor-guides/content/search-content)         | This document contains information on how to use the built in search tool in the content editor.                                                                                                                                                                       |
| [Filter content](/docs/editor-guides/content/filter-content)         | This document contains information on how to create filters to easily find content entries. It also covers how different filters display according to your Schema configuration, general filter conditions and step-by-step instructions on how to use system filters. |
| [Localize content](/docs/editor-guides/content/localize-content)     | This document contains information on how to work with translations. It covers adding translations to an existing entry, adding translations to a new entry, and how to show and hide translations.                                                                    |
| [Publish content](/docs/editor-guides/content/publish-content)       | This document contains information about content publishing. It covers basic information on content stages, how to publish already created content, and scheduled publishing.                                                                                          |
| [Delete content](/docs/editor-guides/content/delete-content)         | This document contains information on how to delete content both from the content table itself, as well as from inside the content entry.                                                                                                                              |
| [Duplicate content](/docs/editor-guides/content/duplicate-content)   | This document contains information on how to duplicate content.                                                                                                                                                                                                        |
| [Field types](/docs/editor-guides/content/field-types)               | This document contains information on how to work with all the different types of fields that you may find as an Editor in a content entry.                                                                                                                            |
| [Conditional fields](/docs/editor-guides/content/conditional-fields) | This document contains information on how to work with conditional fields in the content form.                                                                                                                                                                         |

### Collaboration

This section covers our collaboration tools.

| Document                                                         | Contents                                                                                                    |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [Notifications](/docs/editor-guides/collaboration/notifications) | This document contains information on how Hygraph notifications work.                                       |
| [Commenting](/docs/editor-guides/collaboration/commenting)       | This document contains information on how to use the commenting tool when collaborating with other Editors. |

### Other features

This section covers related information you may find useful.

| Document                                                                          | Contents                                                                                                                                            |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Content stages](/docs/editor-guides/other-features/content-stages)               | This document contains information on Hygraph's default content stages, using content staging to compare entry versions, and how to revert changes. |
| [Content versions](/docs/editor-guides/other-features/content-versions)           | This document contains information on content versions, which allow you to view the evolution of the project's published content                    |
| [Content releases](/docs/editor-guides/other-features/content-releases)           | This document contains information on how content releases work, how to create / edit / delete them, and their limits.                              |
| [Configure columns](/docs/editor-guides/other-features/configure-columns)         | This document contains information on how to customize the way the entry forms look in the content table.                                           |
| [Content Workflows](/docs/editor-guides/other-features/content-workflows)         | This document contains information on how to create workflows to manage content creation and approval through a clear, structured process.          |
| [Webhooks](/docs/editor-guides/other-features/webhooks)                           | This document contains basic information on what webhooks are and what they may be used for in your project.                                        |
| [Asset manager](/docs/editor-guides/other-features/asset-manager)                 | This document contains information about the asset manager. Learn how to work with assets, how to upload assets, and how to create an asset entry.  |
| [Editor best practices](/docs/editor-guides/other-features/editor-best-practices) | This document contains a list of suggested Editor best practices.                                                                                   |

&nbsp;

&nbsp;


---
# Asset manager

Source: https://hygraph.com/docs/editor-guides/other-features/asset-manager

## Overview

The **Asset** model is included in every project by default. It is commonly used for images, but can also support any file type. Assets can be fetched, referenced, transformed, uploaded, updated, published, localized, deleted, and embedded.

As an Editor, you may have to add assets to content entries using the [asset picker field](/docs/editor-guides/content/field-types#asset-picker).

<Alert theme="info">

One of the great features about Assets in Hygraph is that, depending on project configuration, an asset can also have associated metadata, such as an image caption.

Check out our [Add asset entry](/docs/editor-guides/other-features/asset-manager#add-asset-entry) document section to find out more about this.

</Alert>

## Switch views

You can choose whether you want your assets to display in a grid or table view.

You can find the switch at the top of the screen:

![Switch asset views](/images/docs/user-guides/assets/asset-table-views-switch.png)

### Table view

This is what the table view looks like:

![Assets - Table view](/images/docs/user-guides/assets/asset-list-view.png)

Users can open the asset entry by clicking on a table item, or use the checkboxes to perform single or bulk actions.

### Grid view

This is what the grid view looks like:

![Assets - Grid view](/images/docs/user-guides/assets/asset-table-grid-view.png)

- **Open an entry:** Open an asset entry by clicking anywhere on the thumbnail or the title.
- **Preview asset:** Click on the eye icon on an asset card to open a large asset preview. This icon appears on hover.
- **Asset selection:** Select boxes appear on hover. Selecting an asset activates selection mode. As a result:
    - A deselect all button appears at the top of the grid.
    - All checkboxes become visible on all assets.
    - Clicking on asset cards will not open the asset in selection mode.

## Work with assets

If you have access to the **Assets** section of the app, you will see that the screen displays all uploaded assets in a table. On this screen, you can perform the following actions:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/B2sUCO8TMmAxF2UUtdN6" caption="Asset manager overview" />

- `Filters`: Filter assets by name, or add new filters by clicking on `+ Filter` and selecting one from the list. [Here](/docs/developer-guides/content/using-filters) you can find detailed information on how to work with filters.
- `Edit`: Edit the details of an asset entry by clicking on the pencil icon.
- `Configure columns`: This option allows you to configure the columns that display on the assets table. When you click on this link, a dropdown allows you to select/deselect columns using checkboxes. [Here](/docs/developer-guides/content/configuring-columns) you can find detailed information on how to configure columns.
- `Clear selection`: This option displays only if at least one item from the list has been selected. It clears the selected items.
- `Show selected entries`: This option displays only if at least one item from the list has been selected. Clicking on this option displays only the selected items on the list.
- `Publish`: This option displays only if at least one item from the list has been selected, and starts the publishing process. Clicking on `Publish` prompts a pop up screen where you can use checkboxes to select whether non localizable fields and/or the default localization fields will be published, before clicking on the `Publish` button to finish the process. You can publish entries in batch by selecting multiple entries then clicking on `Publish`, but please consider that when using batch-publishing, non-localized fields and the default localization will always be published.
- `Delete`: This option displays only if at least one item from the list has been selected. Clicking on `Delete` results in the elimination of the selected entries. Please consider that this change is permanent and cannot be rolled back.
- `Schedule`: This option displays only if at least one item from the list has been selected. Clicking on `Schedule` prompts a pop up screen where you can schedule publication by selecting one of the following options:
  - `Schedule entry only`: This option schedules an entry individually. After selecting this option, you'll select an `Action` (publish, or unpublish), a date and time, and a time zone. You can also use checkboxes to select which additional locales are published/unpublished - non-localized fields and the default localization will always be published.
  - `Add to an existing release`: This option allows you to select from existing releases that need to have been previously configured in your content editor. If you have configured releases, then you will be able to select one from a dropdown menu after selecting this option. Otherwise, the following message displays: **No releases available, please add one**.
  - `Add to a new release`: This option allows you to create a new release and add the current entry to it. After selecting this option and giving your new release a `Name` and `Description`, you'll select an `Action` (publish, or unpublish), a date and time, and a time zone. You can also use checkboxes to select which additional locales are published/unpublished.

## Upload asset

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/ip12y5HTbatw8wz2dlUs" caption="Upload an asset" />

1. Navigate to the **Assets** tab of your project and click on the `Upload` button, located at the top right corner of your screen.
2. Select an asset source from the popup screen. Uploading an asset from your device is the default option, but you can select different options:

   - Upload an asset from your device.
   - Provide an asset URL.
   - Search images through web search.
   - Connect the project to a Facebook account to select an asset from it.
   - Connect the project to an Instagram account to select an asset from it.
   - Connect the project to a Google Drive account to select an asset from it.

   You can add assets from one or more of these sources.

3. As you select multiple assets, the pop up screen will display them on a list, where you will have the following options:
   - `Filter`: You can filter assets by name. This is specially useful when you need to find a specific asset in a long list.
   - `Edit`: The `Edit` option allows you to crop the image, create a circular image using part of it, or rotate it.
   - `Eliminate`: The `Eliminate` option simply removes the asset from the list.
   - `Deselect all`: This button clears the assets list.
4. `Upload more`: Optionally, you can upload multiple assets at the same time. To do this, click on `Upload more`, or click on one of the asset source icons then select a new one.
5. `Upload`: This button finishes the process by uploading all selected assets. As a result, the assets will display in the uploaded assets list in stage `DRAFT`. **Don't forget that for a content entry that you publish to display correctly, all associated assets need to be `PUBLISHED` as well**.

## Add asset entry

Out-of-the-box this process works as follows:

![Assets - Add Entry](/images/docs/user-guides/assets-add-entry.png)

To add an asset entry, navigate to the **Assets** tab of your project and click on the `+ Add entry` button, located at the top right corner of your screen.

Unlike our [regular asset upload](/docs/editor-guides/other-features/asset-manager#upload-asset), when you add an asset entry you may have more options depending on configuration, such as the possibility to add a caption.

`Asset` is a system model that appears by default in every Hygraph project. So, a system administrator could edit this asset model to include other necessary information. This asset model configured in your project's schema will determine the data you can add to an asset entry.

<Alert title="Pro Tip" theme="info">

It's important to note that the fields that can be added to the asset model are the same [field types](/docs/editor-guides/content/field-types) that can be added to any model, and work the same way.

</Alert>

This is what the **Add asset entry** screen looks like by default:

![Assets - Add Entry](/images/docs/user-guides/assets-add-entry-screen.png)

Besides the metadata - that may or may not display here depending on configuration - the `+ Add entry` screen has an `Upload` button that displays the same options as our [regular asset upload](/docs/editor-guides/other-features/asset-manager#upload-asset).

The following is an example of what the option to create an asset would look like having a caption field:

![Asset picker - customized](/images/docs/editor-guides/create-content/asset-picker-customized.png)

While it's not possible for us to anticipate all possible customizations of this field, know that if this screen does not display the default view, customization is the reason.

## Integrations

Some apps that manage assets can be integrated with your project. This section contains information on how to use them.

Whether this is available to you or not, depends on project configuration and integrated apps.

### Bynder

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/7T8ZkDysSmGqmZSJafqB" caption="Select asset from Bynder" />

1. Navigate to the **Content** editor.
2. Select the view that you will be working on.
3. Click on `+ Add entry` at the top right of the screen or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Bynder asset** section of the screen and click on `Select asset from Bynder`. A new screen displays showing the assets available in your Bynder domain.
5. Select the asset you want to add to the entry, then click on `Add asset`.
6. Now that the asset has been added to the entry, you can click on `Save` or `Save & Publish`, depending on the workflow you follow.

### Cloudinary

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/KULrcVoSrS7cgKs5LWHQ" caption="Add asset from Cloudinary" />

1. Navigate to the **Content** editor.
2. Select the view that you will be working on.
3. Click on `+ Add entry` at the top right of the screen or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Cloudinary asset picker** section of the screen and click on `Add from Cloudinary`. A new screen displays showing the assets available in your connected Cloudinary account.
5. Select the asset you want to add to the entry, then click on `Add asset`.
6. Now that the asset has been added to the entry, you can click on `Save` or `Save & Publish`, depending on the workflow you follow.


---
# Configure columns

Source: https://hygraph.com/docs/editor-guides/other-features/configure-columns

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/4x6zdeYnQnuLTB9xpz7g" caption="Configure columns in content editor" />

You can configure the columns that display in the content editor so that you can only see information that is relevant to you.

To configure the displayed columns:

1. Navigate to the content editor and find the view you want to modify.
2. Click on the cog icon in the upper-right corner of the table to display the options.
3. Use the eye icons to select which columns you want to show in your content view table. An open eye means shown, and a closed eye means hidden. You can optionally rearrange the columns by clicking on the six dots icon next to the column title and dragging them into the order you want.
4. You can save this as a [custom view](/docs/editor-guides/content/content-editor#custom-views) for easy access in the future, as you can see in the video, or simply click outside the selection popup to close it without saving.


---
# Content releases

Source: https://hygraph.com/docs/editor-guides/other-features/content-releases

## Overview

<Alert theme="warning" title="Feature availability">
This feature is only available for **Enterprise** plans. Please [contact sales](/contact) for further information.
</Alert>

With Hygraph, you can schedule content to be published or unpublished at a specified date & time as a single entry or as a bundle, which we call a "Release".

![Scheduled content in the content editor](/images/docs/editor-guides/other-features/scheduled_content.png)

As an Editor, you may be required to add content to existing releases for scheduled publishing.

Some Editor roles may even need to create releases so that other Editors can use them.

Scheduling a group of entries to be published or unpublished together is a great way of coordinating content across teams.

## Scheduled entries

You will find the option to schedule entries by clicking on the arrow icon of the `Schedule & Publish` button inside the content form:

![Save & Schedule entry option in the content form](/images/docs/editor-guides/other-features/save-and-schedule.png)

When you select this option, you will have the following scheduling options:

![Scheduling options](/images/docs/editor-guides/other-features/scheduling-options.png)

- Schedule entry only
- Add to an existing release
- Add to a new release

### Schedule entry only

This option lets you publish or unpublish individual content entries at a specified date and time.

![Schedule entry only](/images/docs/editor-guides/other-features/schedule-entry-only.png)

1. Use the radio buttons in the `Action` section to select if the entry should be published, or unpublished.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

2. Use the [calendar icon](/docs/editor-guides/content/field-types#date-and-time) to set a date and time. The system also lets you manually type in the date in the format that's visible on the field as an example.
3. Use the `Timezone` dropdown to select one of the available timezones.
4. Use the checkboxes to select which locales to include. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.
5. If you have any references linked to the entry you are scheduling, you can schedule those individually too.

![Schedule Related Entries](/images/docs/user-guides/schedule-relations.png)

### Add to an existing release

This option lets you add this content entry to an existing content release:

![Add to an existing release](/images/docs/editor-guides/other-features/add-to-an-existing-release.png)

1. Use the `Release` dropdown to select the release you want to add this entry to.
2. Use the radio buttons in the `Action` section to select if the entry should be published, or unpublished.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

3. Use the checkboxes to select which locales to include. Non-localized fields and the default locale are required here, but you can choose which of the additional locales to publish or unpublish.

### Add to a new release

This option lets you create a content release to add this content entry to:

![Add to a new release](/images/docs/editor-guides/other-features/add-to-a-new-release.png)

1. Give the new release a `Name` and, optionally, a `Description`.
2. Use the radio buttons in the `Action` section to select if the entry should be published, or unpublished.

    <Alert theme="info" title="Pro Tip">

    If the project has more than the two default stages - `PUBLISHED` & `DRAFT` - this section will also show the `Stage to publish` dropdown, which you can use to select which of the project stages to publish to.

    ![Stage to publish](/images/docs/user-guides/stage-to-publish.png)

    The `Unpublish` action moves content to the `DRAFT` stage.

    </Alert>

3. Use the [calendar icon](/docs/editor-guides/content/field-types#date-and-time) to set a date and time. The system also lets you manually type in the date in the format that's visible on the field as an example.
4. Use the `Timezone` dropdown to select one of the available timezones.
5. Use the checkboxes to select which locales to include.
6. If you have any references - such a images o other content entries - linked to the entry you are scheduling, you can use the checkboxes to schedule those too.

![Schedule Related Entries](/images/docs/user-guides/schedule-relations.png)

## Scheduled releases

### Create content releases

To create content releases:

![Scheduled publishing - Create a content release](/images/docs/editor-guides/other-features/create-release.png)

1. Navigate to the **Content editor** and locate the `Schedule` section at the top of the `Content` sidebar.
2. Click `Releases`.
3. Click `+ Add release`. You can find this button at the top right corner of the screen or, if there are no releases yet, in the middle of the screen.
4. Complete the required information in the **Add release** panel:
   - `Name`: Type a name to identify your release.
   - `Description`: Optional. You can write a description for your release here.
   - `Date and Time`: Optional. Use the [calendar picker](/docs/editor-guides/content/field-types#date-and-time) to set a date and time.
   - `Timezone`: Optional. Use the dropdown to select a timezone.
   - Click on `Add` to finalize the process.

### Edit content releases

To edit an existing content release:

![Scheduled publishing - Edit a content release](/images/docs/editor-guides/other-features/edit-release.png)

1. Navigate to the **Content editor** and locate the `Schedule` section at the top of the `Content` sidebar.
2. Click `Releases`.
3. Click on the context menu (the three docs icon) of the content release you want to edit, and select `Edit`.
4. You can make change the Name, Description, use the [calendar picker](/docs/editor-guides/content/field-types#date-and-time) to edit the date and time, or use the dropdown to edit the timezone.
5. Click `Update` to save the changes.

If you click on a release on the table to view its details, you will also find an `Edit release` button at the top-right corner of the screen:

![Scheduled publishing - Edit a content release](/images/docs/editor-guides/other-features/edit-release-alternative.png)

### Delete content releases

To delete an existing content release:

![Scheduled publishing - Edit a content release](/images/docs/editor-guides/other-features/delete-release.png)

1. Navigate to the **Content editor** and locate the `Schedule` section at the top of the `Content` sidebar.
2. Click `Releases`.
3. Click on the context menu (the three dots icon) of the content release you want to edit, and select `Delete`.
4. Since this change is a permanent action that cannot be undone, you will need to confirm by clicking on `Delete release` on the confirmation popup.

## Limits

- Any changes to your `DRAFT` content will be included with any pending scheduled release(s).
- You can have a maximum limit of 50 pending releases, and 50 items in a single release.
- You can have a maximum of 200 pending scheduled items overall within your project environment.


---
# Learn about content stages

Source: https://hygraph.com/docs/editor-guides/other-features/content-stages

## Default stages

Hygraph has two default stages, `DRAFT` and `PUBLISHED`. `DRAFT` allows people to add and edit content without affecting published content. When the content is ready to be pushed, it is added to the `PUBLISHED` stage.

<Alert theme="warning">

Some projects may have custom content stages depending on plan and configuration.

</Alert>

You can see the stage of a content entry on **Stages** column of the form in the content editor:

![Content stages](/images/docs/editor-guides/other-features/stages-column.png)

Note that the `PUBLISHED` stage tag is sometimes green and sometimes blue.

- `Green` means that the contents of the entry are the same as the contents currently published.
- `Blue` means that the published content is outdated, that is, that the contents of the entry are a newer version than what is currently published.

Clicking on `Publish` will update the version currently live so that the contents are the same as the entry.

![Publish button](/images/docs/editor-guides/other-features/publish-outdated-content.png)

Note that if you make any changes to the content entry, this button will say `Save & Publish` instead.

Check out our [Update content](/docs/editor-guides/content/update-content) document to learn more.

## Content staging

Content staging is a useful tool that allows Editors to compare versions of content in different stages. Remember that content might be in the blue `PUBLISHED` stage, meaning it is [outdated](/docs/editor-guides/content/update-content#outdated-content) - the version online is different from the version in your content editor.

To compare versions:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/xtOSTlnRh2jC9mhxf2nZ" caption="Compare content versions" />

1. Navigate to the entry you want to compare in the content editor, and access its contents by clicking on the pencil icon.
2. Find the `Stages` section on the sidebar.
3. Click on the dropdown menu to display the options, and click on `Compare with current draft`.

You will get a side by side view of both entries. The live (currently published) version displays on the right of the screen, while your `DRAFT` or outdated version displays on the left.

<Alert theme="success">

This feature can be particularly helpful when using [Custom Roles](/docs/editor-guides/basic-navigation/roles-permissions#custom-roles) to create more sophisticated workflows for the team.

For example, if a team member should only be able to create `DRAFT` content but not move it directly to the `PUBLISHED` stage, this is possible with Custom Roles.

</Alert>

---
# Content versions

Source: https://hygraph.com/docs/editor-guides/other-features/content-versions

Content versioning lets you track changes in published content over time. When versioning is enabled, a new version is created with each published change.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xausjawf07w5hpa78xlh" caption="Version comparison in Hygraph" />

<Alert theme="warning">

Please note that versioning may or may not be enabled in your project. Also, the number of versions that are saved and available to you depend on your company's plan with Hygraph.

</Alert>

To create a new version of your content, simply click `Save & publish` or `Publish` after editing the contents.

New versions will be visible on the sidebar of your content entry's edit view, in the **Versions** section:

![Versions section on the sidebar panel](/images/docs/user-guides/content-versions-panel.png)

<Alert theme="warning">

New versions are created when you publish content to any stage. `DRAFT` content is not versioned, and its revision history is not available. Version history is only retained for content published to other stages.

</Alert>

## Compare and restore versions

As an editor, you can compare versions across [content stages](/docs/editor-guides/other-features/content-stages) to track changes over time. If you need to revert updates from the `PUBLISHED` stage back to `DRAFT`, you can review both versions side by side and restore specific fields as needed.

This saves time and prevents duplicate work when rolling back changes.

![Version comparison - Comparison view](/images/docs/user-guides/version-comparison-view.png)

To compare and restore versions, open a content entry and navigate to the **Versions** section in the right sidebar. Click on the version you want to compare against the currently published version. This will open a split-pane view, displaying the draft version on the right and the published version on the left.

Fields that have been edited are marked with an `Edited` pill in the right panel, making it easy to identify differences. To restore a specific field, hover over it and click `Restore`. If you want to revert all changes at once, use the `Restore all changes` button at the top-right of the screen.

Click `Apply changes` to go back to the content form, where the entries you selected show the restored content.

When you click `Save & Publish`, the system will generate a new version that includes the latest changes.

---
# Learn about Content Workflows

Source: https://hygraph.com/docs/editor-guides/other-features/content-workflows

## Overview

<Alert title="Please note" theme="info">

As an Editor you are not likely to configure Content Workflows, but you may have to work con content that follows a specific workflow. This document teaches you how to work with this feature.

</Alert>

**Content workflows** in Hygraph help teams manage content creation and approval through a clear, structured process.

Publishing often involves steps like reviews, QA, translations, and asset creation. Without a workflow, teams can face issues such as inconsistent content, lack of transparency, and publishing errors. Content Workflows address these challenges by guiding content through an organized, step-by-step path from draft to publication.

## Working on a content entry that is part of a workflow

When you open a content entry, the system checks if it is assigned to a workflow, and if editing is allowed:

- **If editing is not allowed**, you will access a read-only version of the content entry. You can read the entry and leave comments, but you cannot modify the contents. You can also move it to the next step in the workflow if you have this permission.
- **If editing allowed**, you can work on it normally.

On the sidebar, you can see what workflow step the entry is on. The sidebar always shows which roles can work on the content entry.

![Workflows in content entries](/images/docs/user-guides/workflows_sidebar_widget.png)

If a workflow step is assigned to an [AI agent](/docs/hygraph-ai/ai-agents), the agent automatically starts processing as soon as an entry moves into that step. This ensures tasks run seamlessly within the defined workflow.

### Move a content entry along the workflow

If you have permission to move the entry to the next step in the workflow, the `Move to` button at the top-right of the screen will be enabled.

You can click `Move to`, to move the entry to the next step in the workflow, or click the arrow icon to display the workflow actions.

![Content workflows - entry actions](/images/docs/user-guides/workflows_entry_actions.png)

You may see some or all of these workflow actions depending on your role & permissions:

| Workflow action                    | Description                                                                                                                                                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Return to`                        | Select this option to return the content entry to its configured return step. This option is enabled only if the workflow step has a `Return to` step configured.                                                                   |
| `Move forward to`                  | Select this option to move the content entry to the next step in the workflow.                                                                                                                                                      |
| `Override workflow for this entry` | Select this option to override the workflow for the entry. When you override the workflow, you can perform any actions, just as if there wasn't a workflow configured. This option is enabled only if you have override permission. |

### Publish a content entry in the workflow

If you move a content entry into a step with `Publish to` configured, the entry will automatically be published to the configured stage. You can publish entries to intermediate content stages such as `QA`, or to `PUBLISHED`.

When publishing an entry to the `PUBLISHED` stage, you will have the option to publish it right away or to schedule publishing.

#### Publish now

This action publishes your content to the `PUBLISHED` stage, meaning it will be available online for others to consume. If your content entry contains unpublished assets or references, you will be prompted to publish those too.

Moving an entry to the next step & publishing at the same time is an atomic operation. This means both events will succeed or fail.

#### Schedule publishing

If you select scheduled publishing, the side sheet will open for you to schedule publication of the content entry.

<Alert theme="info" title="Pro Tip">

When you schedule an entry to publish to a stage, the workflow will move it to that stage but since publishing is scheduled in the future, it will not be published right away. If you open the content entry at this time, it will display as read-only.

In order to avoid workflow inconsistencies, the only way to edit this entry is to return it to the previous step, if you have the permission.

</Alert>

[Check out our scheduled publishing docs](/docs/developer-guides/content/scheduled-publishing) to learn how to schedule single entries or add them to a release.


---
# Best practices for Editors

Source: https://hygraph.com/docs/editor-guides/other-features/editor-best-practices

- Save the drafts often as you are working on content pieces. This will prevent any loss of work if there are unforeseen issues.
- Use [content stages](/docs/editor-guides/other-features/content-stages) and [versioning](/docs/editor-guides/other-features/content-versions) to make sure that teams have an active record of their work.
- Use the [Markdown field](/docs/editor-guides/content/field-types#markdown) when you want to preview content formatting. This field is particularly helpful for larger blocks of text and adding links, quotes, formatted text.
- When using the [Rich Text field](/docs/editor-guides/content/field-types#rich-text), it is a good idea to optimize your images into a web-friendly format like `WebP` to optimize the loads on your front end.
- Make sure you publish all assets and any referenced content when you are publishing new content. Hygraph is intended to be modular with content that is able to be reused in different contexts. Because of this, each asset and reference field has its own permissions which need to be updated when publishing new content.


---
# Learn about webhooks

Source: https://hygraph.com/docs/editor-guides/other-features/webhooks

<Alert title="Please note" theme="info">

- The default Editor role available for all Hygraph projects does not see this section on the screen.

- As an Editor you will not need to configure webhooks, but knowing what they are and how they work might help you better understand how your content behaves.

</Alert>

Webhooks are essentially triggers that start an action whenever another action occurs in the CMS. For example, clicking on `Publish` in a content entry could trigger a website build in an external service.

Webhooks can be used to trigger new website builds, or syncing data with an external service, such as a PIM. For marketers, another important use case could be sending notifications to a teammate when content is added or triggering email campaigns based on new published content.

Your development team will set up webhooks in your project depending on project needs.


---
# Use Click to Edit

Source: https://hygraph.com/docs/editor-guides/visual-editing/click-to-edit-editors

Click to Edit lets you click any element in the live preview to jump directly to that field in the entry form.

## Prerequisites

Click to Edit requires your developer to [have installed the Hygraph Preview SDK and added the necessary markup to your frontend](/docs/developer-guides/schema/click-to-edit) and [configured a Preview widget and preview URL for your content model](/docs/developer-guides/schema/live-preview).

If you open a live preview and no **Edit** buttons appear anywhere in the preview, the SDK setup is incomplete. Ask your developer to verify the setup.

Edit buttons do not appear on every field. Developers choose which elements to configure as editable, such as titles, descriptions, hero images, and the blocks editors touch most. If a field you frequently update is missing a button, ask your developer to add it; the content entry form is always there as a fallback.

## Use Click to Edit in Studio

Studio loads the preview in a side-by-side panel alongside the entry form.

<Video>
  <source
    src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmovnioa57t8j07w9bsqaxnhc"
    type="video/mp4"
  />
</Video>

1. Open the content entry you want to edit.
2. In the right sidebar, click **Open live preview**. The preview loads next to the entry form.
3. Hover over an element in the preview. An **Edit** button appears on elements your developer has configured as editable.
4. Click **Edit**. Studio scrolls to and focuses the corresponding field in the entry form.
5. Make your changes to the field.
6. Click **Save & Preview**. The preview shows your saved content.

The preview holds your scroll position when it refreshes, so you stay oriented in the page as you edit.

<Alert theme="info" title="The preview updates on save, not as you type">
The preview refreshes after you save, not while you are typing. If your team has enabled live field updates, changes appear in the preview immediately as you type. Ask your developer if you are unsure which is configured.
</Alert>

## Use Click to Edit in standalone mode

If your developer has configured standalone mode, the **Edit** buttons appear directly on your preview site in a regular browser tab, outside Studio. Clicking Edit navigates you to the correct field in Studio without any risk of affecting other entries or content.

<Video>
  <source
    src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmovnl25i87c407w4zyoq1sy0"
    type="video/mp4"
  />
</Video>

1. Open your preview site in a browser.
2. Hover over an element. An **Edit** button appears on elements your developer has configured as editable.
3. Click **Edit**. Studio opens in a new tab and takes you directly to the field.
4. Make your changes to the field.
5. Click **Save & Preview**. 
6. Go back to the preview and check your changes. The preview shows your saved content.

## Click to edit for locales

Clicking **Edit** while previewing a locale opens the correct field in Studio in the default locale. Select your target locale field manually after the field opens.

After you open live preview, follow these steps to edit the field for the target locale:
1. Use the locale switcher in the preview panelto open the preview for the target locale.
2. Hover over an element. An **Edit** button appears on elements your developer has configured as editable.
3. Click **Edit**. You are taken to the field for the default locale.
4. Select the target locale field that you want to edit. Locale fields appear below the default locale field.
5. Make your changes.
6. Click **Save & Preview**. The preview shows your saved content.

<Video>
  <source
    src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmowrrfomdqyh07upz2em2pl0"
    type="video/mp4"
  />
</Video>

## Troubleshooting

### Edit buttons do not appear

The Preview SDK is not installed or is not wrapping your page content correctly. Ask your developer to verify the setup.

### Edit button appears but nothing happens when clicked

Check that your browser is not blocking new tabs. In standalone mode, Studio opens in a separate tab. Confirm your browser allows this from your preview site.

### Preview does not refresh after saving

Confirm you used **Save & Preview** instead of **Save**. If the preview still does not update, ask your developer to check the save callback configuration.

### Preview panel is blank or shows a security error

Your site is blocking iframe embedding. This is a server configuration issue, not a content issue. Ask your developer to check the `X-Frame-Options` and `Content-Security-Policy` headers on your frontend.

## What's next

- [Live preview](/docs/editor-guides/visual-editing/live-preview-editors): How the side-by-side preview panel works and how to save and refresh correctly.
- [Edit content](/docs/editor-guides/content/edit-content): How to edit fields directly in the entry form.
- [Content stages](/docs/editor-guides/other-features/content-stages): The difference between Draft and Published and what **Save & Preview** does to your content.

---
# Live preview

Source: https://hygraph.com/docs/editor-guides/visual-editing/live-preview-editors

Live preview loads your website in a panel alongside the entry form in Studio. You see exactly how your draft content looks on the actual site before you publish it, and you can keep editing while the preview stays open.

## Prerequisites

Your developer must have [configured a Preview widget and preview URL for your content model](/docs/developer-guides/schema/live-preview). If **Open live preview** does not appear in the right sidebar when you open an entry, ask your developer to check the setup.

## Open live preview

The entry must exist in the `DRAFT` stage before the **Open live preview** button appears. If you are creating a new entry, save it first before opening the preview.

![Open live preview](/images/docs/user-guides/live-preview/live-preview-open.png)

1. Navigate to **Content** and open the entry you want to preview.
2. In the right sidebar, click **Open live preview**. If more than one preview link is configured, you can use the dropdown menu to select a preview link.
        ![Live preview - Dropdown selection](/images/docs/user-guides/live-preview/live-preview-selection.png)
3. Make changes to any field in the entry form.
4. Click **Save & Preview** to save your changes and refresh the preview.

The preview shows your draft content, that is, changes you have saved but not yet published. It does not show changes you have typed but not saved.

![Live preview](/images/docs/developer-guides/visual-editing-live-preview.png)

<Alert theme="warning">
**Save** saves your changes but does not refresh the preview. **Save & Preview** saves your changes and refreshes the preview. If you save without clicking **Save & Preview**, the preview continues to show the previous version of your content.
</Alert>

## Switch view size

At the top of the preview panel, three buttons let you switch between screen sizes: desktop, mobile, and full width. Use this to check how your content looks across different devices before publishing.

<Video>
  <source
    src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmovey9utkfff06w2rvvi4s1z"
    type="video/mp4"
    caption="Switch view"
  />
</Video>

## Switch locale

If your project has multiple locales configured, a locale switcher appears in the preview panel. Use it to switch between locales and see how your content looks in each language without leaving the preview. If the locale switcher does not appear, ask your developer to [set it up](/docs/developer-guides/schema/live-preview#define-a-preview-url-template).

<Video>
  <source
    src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmovfakupm0st06w2jrggq67d"
    type="video/mp4"
     caption="Switch locale"
  />
</Video>


## Troubleshooting

### Blank preview panel or security error

Your site's security configuration is blocking the preview from loading inside Studio. This is a server configuration issue. Ask your developer to check the `X-Frame-Options` and `Content-Security-Policy` headers on your frontend.

### Open live preview button is missing

Save the entry first. The button only appears once the entry exists in the `DRAFT` stage. If the button is still missing on a saved entry, ask your developer to verify the Preview widget is configured for this content model.

### Preview shows old content after saving

Click **Save & Preview** rather than **Save**. If the preview still shows old content after using **Save & Preview**, ask your developer to check whether caching is active in the preview environment.

### Preview shows a 404 or wrong page

The preview URL configured for this content model may be pointing to the wrong route. Ask your developer to verify the URL in the Preview widget settings.

## What's next

- [Use Click to Edit](/docs/editor-guides/visual-editing/click-to-edit-editors): How to use Click to Edit in Studio and standalone mode, and what to do when Edit buttons are missing.
- [Edit content](/docs/editor-guides/content/edit-content): How to edit fields directly in the entry form.
- [Content stages](/docs/editor-guides/other-features/content-stages): The difference between Draft and Published, and what saving does to your content stage.


---
# Visual editing

Source: https://hygraph.com/docs/editor-guides/visual-editing/visual-editing-overview-editors

Visual editing lets you review and change content directly from a live preview of your frontend. Instead of editing fields by name in a form and guessing how the result will look, you see the actual page and edit from it. Nothing you do in the preview panel publishes your content: saving updates the preview, not the live site.

## What is visual editing?

Without visual editing, you edit fields in the content entry form and guess what the result looks like. With it, you see the actual page and click what you want to change.

### Live preview

![Live preview](/images/docs/developer-guides/visual-editing-live-preview.png)

Live preview shows your draft content rendered in the frontend, side by side with the entry form. If your project uses multiple locales, a locale switcher appears in the preview panel. When you open an entry, you can see exactly how your draft content looks on the actual site before you publish it. You make changes in the entry form, save, and the preview refreshes.

### Click to Edit

![Click to Edit](/images/docs/developer-guides/visual-editing-click-to-edit.png)

Click to Edit adds Edit buttons to elements in the preview so you can jump directly to any field. You hover over any element in the preview and click **Edit** to jump directly to that field in the entry form. You no longer need to navigate to the right field in the content entry form manually.

## What your developer needs to set up

Your developer needs to configure Visual editing before you can use it. You cannot enable it yourself from the content editor.

For [live preview](/docs/developer-guides/schema/live-preview), your developer needs to:
- Add a Preview widget to your content model in the schema builder and configure a preview URL
- Configure your frontend to serve draft content so unpublished changes are visible in the preview

Once this is done, the **Open live preview** button appears in the right sidebar when you open a content entry. If the button does not appear, or the preview panel is blank, ask your developer to verify the setup.

For [Click to Edit](/docs/developer-guides/schema/click-to-edit), your developer needs to:
- Install the Hygraph Preview SDK and add the necessary markup to your frontend

Once this is done, Edit buttons appear on elements in the preview. If no buttons appear, ask your developer to verify the setup.

## What's next

- [Live preview](/docs/editor-guides/visual-editing/live-preview-editors): How to open the preview panel, save and refresh, and switch between preview URLs.
- [Use Click to Edit](/docs/editor-guides/visual-editing/click-to-edit-editors): How to use Click to Edit in Studio and standalone mode, and what to do when Edit buttons are missing.

---
# Cursor + Hygraph

Source: https://hygraph.com/docs/implementations/ai/cursor

## Overview

If you're new to frontend implementation, you can use AI to help out!

This guide shows you how to use <Link href="https://www.cursor.com/" target="_blank">Cursor</Link> to create a frontend implementation for your Hygraph project.

<Alert theme="info">

As with anything being generated by AI, the more you know about the underlying technologies you work with, the smoother the process.

Basic understanding of the framework you choose and debugging common issues with it will make the process of generating code with AI much smoother.

</Alert>

## HYGRAPHlix & Cursor

This example uses the **HYGRAPHlix starter**. <Link href="https://app.hygraph.com/clone/60a5f60969474157a5bb6cec6452e833?name=Hygraph%20Movie%20Platform%20Starter" target="_blank">You can clone this project here</Link>.

<VideoEmbed videoId="iVvTq9qu8Po" />

<Alert theme="info" title="Do you want to do this manually?">

[We have an implementation guide for HYGRAPHlix & Next.js!](/docs/implementations/next/hygraphlix-next)

</Alert>

## Basic step-by-step

After creating your Hygraph project and defining your schema, follow these steps:

### 1. Get Cursor

<Link href="https://www.cursor.com/" target="_blank">Download & install Cursor</Link>.

Start Cursor and open the chat (CMD+L). The chat lets you select which LLM to use. [We use claude-3.5-sonnet in the example](/docs/implementations/ai/cursor#hygraphlix-and-cursor).

<Alert theme="info">

You can alternatively install the Cursor extension for your IDE.

</Alert>

### 2. Write the prompt

![Use Cursor to implement your Hygraph project](/images/docs/implementations/cursor/hygraphlix-cursor.png)

Write a prompt in the Cursor chat. A prompt is the set of instructions that you provide as input to generate a response or perform a task based on the context, which you must also provide.

Your prompt should state all the necessary information. [Check out the prompt example we wrote for you](/docs/implementations/ai/cursor#how-to-write-a-prompt).

#### How to write a prompt

While we cannot guarantee that Cursor will provide the same answer each time, here is a prompt that we used with great results!

```
Make a Next.js project with Tailwind that is designed to look like Netflix
This project should have a homepage and a dynamic route pulling data from a Hygraph endpoint with a GraphQL query that looks like this:

query MyQuery {
  movies {
    title
    movieInfo: federateMovie {
      data {
        Title
        Plot
        Director
        Genre
        Runtime
        Poster
      }
    }
    imdbId
    slug
moviePoster {
      url
    }
  }
}

The homepage should have a card style for each movie
Each movie page should check for a moviePoster URL and if it doesn't exist use the movieInfo image instead
The project should be set up to use images from either *.graphassets.com or m.media-amazon.com domains
This should use the App router and not use getStaticPaths
Please create the directory structure and the files necessary
```

As you can see, the prompt above offers all the necessary information. The more comprehensive your prompt is, the less debugging you will need to work on to get the project up and running.

We started by defining the framework and library we want the frontend implementation to use, and then we indicated what we want it to look like, visually.

We also state that it will require a dynamic route that pulls data from a Hygraph endpoint with a GraphQL query that should look like an example that we also provided.

<Alert theme="info" title="Pro Tip">

You can easily build your queries using our [API Playground](/docs/getting-started/studio-walkthrough#api-playground)!

</Alert>

Since the project uses remote sources for some of the images, we state how the images should be fetches when a moviePoster is not available.

If you'd like to follow the step by step of how we used this prompt to create a frontend for one of our starter projects, [check out our implementation example!](/docs/implementations/ai/cursor#hygraphlix-and-cursor)

### 3. Follow the instructions

Cursor will provide steps:

- For the steps where you need to run a command, click `Run` to run them in the command line.
- For the steps where you need to add bits of code into files in your project, you can click `Apply` or copy the code and paste it into the file.
- In some cases, you will need to create these files - and even a folder to contain them - which Cursor will indicate in the instructions preceding the code snippet. The IDE will prompt you to accept the changes made by Cursor.

Go over the steps running the commands and adding the files & code using the flow laid out by cursor. At the end of this flow, run the app locally to see if it works. [Troubleshooting might be necessary](/docs/implementations/ai/cursor#troubleshooting).

#### Troubleshooting

When running your app locally, you might get errors. This is where some experience debugging code might come in handy! Copy and paste the errors in the Cursor chat indicating that this is an error you're getting.

Cursor will explain the error and provide a solution - which might contain several steps and involve modifying several of your project files.

Follow the instructions and apply the changes, then check your app locally again.

You may have to repeat this process several times, until you've fixed all errors.

<Alert theme="info" title="Pro Tip">
If, at some point, any of the changes you apply while troubleshooting cause your app to crash, you will see this in the command line.

Copy the error you get there and paste it on the cursor chat, just like you did before.

Cursor will, again, provide a solution that you need to apply.
</Alert>


---
# Astro + Hygraph

Source: https://hygraph.com/docs/implementations/astro/astro

## Overview

<Link href="https://astro.build/" target="_blank">Astro</Link> is an all-in-one web framework for building content-driven websites like blogs, marketing, and e-commerce. It has everything you need to create a website built-in.

You can use Astro with any JS framework — React, Svelte, etc — or none at all.

## Creating a new Astro app

To start, we need to initialize a new `Astro` project. Open up your terminal, navigate to where you want your project, and run the following command:

```
npm create astro@latest
```
To create an Astro app with an example implementation of Tailwind CSS, run the following command:

```
npm  create astro@latest -- --template with-tailwindcss
```

<Alert theme="warning">
We will use Astro with an example implementation of Tailwind CSS in the Getting data from Hygraph section of this guide.
</Alert>

### Configure Hygraph assets to work with Astro

To work with the Astro image module `<Image/>`, we need to specify Hygraph as an image domain by adding the domain URL in the `astro.config.mjs file`.

Your config file should contain the following code:

```js
// File: astro.config.mjs
export default defineConfig({
  image: {
    // Example: allow processing all images from Hygraph
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.graphassets.com',
    }],
  },
});
```

## Getting data from Hygraph

Now that you have created your Astro project, it's time to add some data from Hygraph. Start by cloning our demo Hygraph project:

<Button
  href="https://app.hygraph.com/clone/751a6bdf9431476c8b82c543895e6d16?name=Implementation%20Guides"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Click here to clone the demo project</Button>

After cloning, you will have a simple project that contains one content model called **Page** that contains fields for `Title`, `Slug`, and `Body`; and one content entry.

If you navigate to the Schema builder and click on the **Page** model, you will see this:

![Demo project - Page model](/images/docs/implementations/demo-project-page-model.png)

And if you navigate to the Content editor and view the sample entry details, you'll see this:

![Demo project - Sample content entry](/images/docs/implementations/demo-project-sample-entry.png)

## Content API

Before you can connect Astro to Hygraph, you will need to configure **Content API** access permissions for unauthenticated requests.

To do this, we'll to go **Project settings > Access > API Access > Content API** in our Hygraph project, scroll to find the **Manage Content API access permissions** box and click `Initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, we will copy the `High Performance Read-only Content API` endpoint from **Project settings > Access > API Access > Endpoints**. You will use it to connect Astro to Hygraph later on.

## Testing a query in the API playground

Next, you should test if you can fetch the information in the sample content entry that we showed you earlier. To do this, navigate to the API Playground in your project and use the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query Page {
  page(where: {slug: "hygraph-works-with-any-framework"}) {
    title
    body {
      text
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "page": {
      "title": "Hygraph works with any framework!",
      "body": {
        "text": "No matter the framework you choose, Hygraph is there for you and all your content needs. "
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

If you execute the query, the response should fetch the sample query in the demo project you cloned.

## Connecting Astro to Hygraph

In `Astro`, save your `HYGRAPH_ENDPOINT` in an `.env` file on the project root.

As a result, you will be able to call this key with `import.meta.env.HYGRAPH_ENDPOINT` in any of your files.

This will be where we paste [the endpoint URL we copied from Hygraph](/docs/implementations/astro/astro#content-api):

```
ASTRO_HYGRAPH_ENDPOINT=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```

Your root directory will include the following files:

![Astro implementation - Endpoint URL](/images/docs/implementations/astro/astro-implementation-src.png)

Do you want to see `Astro` and `Hygraph` in action? Watch a quick video on how to connect them:

<VideoEmbed videoId="AAHu9X5WAjY"/>

## Generating Hygraph content with Astro

[After enabling API access](/docs/implementations/astro/astro#content-api), you can start using the **Pages** query with your Astro app to render content.

### Installing a GraphQL Client

GraphQL clients make communication easier by abstracting away small details and implementing additional features such as static typing of our query results.

We will use the npm package `graphql-request` because it is lightweight, has excellent TypeScript support, and supports both `Node.js` and browsers.

Use the terminal to go back to your Astro app, and type the following command:

```
npm add graphql-request
```

This will install a GraphQL client.

### Getting a list of pages for the homepage

After install the GraphQL client, go to the `src` directory and create a directory called `pages` with a file called `index.astro`, and add the following code:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// File location: /src/pages/index.astro
// Homepage: Get a list of pages from the Hygraph
---
import { GraphQLClient } from "graphql-request";
import Main from "../layouts/main.astro";

// Create a new GraphQL client with the Hygraph endpoint
const client = new GraphQLClient(import.meta.env.ASTRO_HYGRAPH_ENDPOINT);

// Fetch the data via the GraphQL query
const { pages } = await client.request(`
  query Pages {
    pages {
      title
      slug
      body {
        text
      }
    }
  }`);
---
<Main title="Hygraph Implementation Guides demo">
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">Hygraph Implementation Guides demo</h1>
    <p class="mb-4 text-lg">Click the links below to see other pages</p>
    <ul class="mb-8 list-disc list-inside">
      {
        pages.map((page: any) => {
          return (
            <li>
              <a href={`/page/${page.slug}`} class="underline">
                {page.title}
              </a>
            </li>
          );
        })
      }
    </ul>
    <p>
      <a
        class="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700"
        href="https://hygraph.com/docs/implementations"
        target="_blank"
      >
        Implementation Docs
      </a>
    </p>
  </div>
</Main>
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// File location: /pages/index.vue
// Homepage: Get a list of pages from the Hygraph
---
import { GraphQLClient } from "graphql-request";
import Main from "../layouts/main.astro";

// Create a new GraphQL client with the Hygraph endpoint
const client = new GraphQLClient(import.meta.env.ASTRO_HYGRAPH_ENDPOINT);
// Declare Pages type
type Pages = {
  pages: {
    title: string;
    slug: string;
    body: {
      text: string;
    };
  }[];
};
// Fetch the data via the GraphQL query
const { pages }: Pages = await client.request(`
  query Pages {
    pages {
      title
      slug
      body {
        text
      }
    }
  }`);
---
<Main title="Hygraph Implementation Guides demo">
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">Hygraph Implementation Guides demo</h1>
    <p class="mb-4 text-lg">Click the links below to see other pages</p>
    <ul class="mb-8 list-disc list-inside">
      {
        pages.map((page: any) => {
          return (
            <li>
              <a href={`/page/${page.slug}`} class="underline">
                {page.title}
              </a>
            </li>
          );
        })
      }
    </ul>
    <p>
      <a
        class="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700"
        href="https://hygraph.com/docs/implementations"
        target="_blank"
      >
        Implementation Docs
      </a>
    </p>
  </div>
</Main>
```
  </TabsItem>
</Tabs>

![Homepage](/images/docs/implementations/next/next-homepage.png)


### Creating dynamic page routes with Astro

Now, that we have a list of pages in our homepage, we need to create a dynamic route for each page. To do this, create a new directory in the `pages` directory called `page` and a file called `[slug].astro` inside this directory.

Add the following code:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// file location & name: src/pages/page/[slug].vue
// Dynamic page: Get a single page by slug from the Hygraph
---
import { GraphQLClient } from "graphql-request";
import Main from "../../layouts/main.astro";

// Create a new GraphQL client with the Hygraph endpoint
const client = new GraphQLClient(import.meta.env.ASTRO_HYGRAPH_ENDPOINT);

export function getStaticPaths() {
  return [
    { params: { slug: "hygraph-works-with-any-framework" } },
    { params: { slug: "any-framework-will-work" } },
    { params: { slug: "implementation-guides" } },
  ];
}

const { slug } = Astro.params;
// Fetch the data via the GraphQL query
const { page } = await client.request(
  `
	query Page($slug:String!) {
		page(where: {slug: $slug}) {
			title
			body {
				text
			}
		}
	}`,
  {
    slug,
  }
);
---
<!--  Renders the homepage with a title and a page fetched from the Hygraph -->
<Main title={page.title}>
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">{page.title}</h1>
    <p class="mb-8 text-lg">{page.body.text}</p>

    <p>
      <a href="/" class="underline">Back to homepage</a>
    </p>
  </div>
</Main>
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// file location & name: pages/page/[slug].vue
// Dynamic page: Get a single page by slug from the Hygraph
---
import { GraphQLClient } from "graphql-request";
import Main from "../../layouts/main.astro";

// Create a new GraphQL client with the Hygraph endpoint
const client = new GraphQLClient(import.meta.env.ASTRO_HYGRAPH_ENDPOINT);

type Page = {
  page: {
    title: string;
    slug: string;
    body: {
      text: string;
    };
  };
};

export function getStaticPaths() {
  return [
    { params: { slug: "hygraph-works-with-any-framework" } },
    { params: { slug: "any-framework-will-work" } },
    { params: { slug: "implementation-guides" } },
  ];
}

const { slug } = Astro.params;

// Fetch the data via the GraphQL query
const { page }: Page = await client.request(
  `
	query Page($slug:String!) {
		page(where: {slug: $slug}) {
			title
			body {
				text
			}
		}
	}`,
  {
    slug,
  }
);
---
<Main title={page.title}>
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">{page.title}</h1>
    <p class="mb-8 text-lg">{page.body.text}</p>

    <p>
      <a href="/" class="underline">Back to homepage</a>
    </p>
  </div>
</Main>
```
  </TabsItem>
</Tabs>

### Code overview

The code you just added will create a dynamic route for each page. It will fetch the page content from Hygraph and render it on the page.

<Alert theme="info" title="Quick Note">
In Astro, all routes are created at build time. This means that you need to specify the paths for the dynamic routes using the `getStaticPaths` function to return an array of paths.
</Alert>

![Dynamic page](/images/docs/implementations/next/next-dynamic-page.png)

Congratulations! You have a homepage and a dynamic page route to render all pages and their content.

<Alert theme="info" title="Pro Tip">
This was a simple and quick example of how to fetch and render content from Hygraph using Astro.

For more complete implementation examples, <Link href="https://app.hygraph.com/" target="_blank">clone a starter</Link>.
</Alert>


---
# Microblog starter + Astro

Source: https://hygraph.com/docs/implementations/astro/microblog-astro

## Overview

Use our Microblog starter with Astro to create a microblog.

## Quickstart: Clone the Astro microblog starter

Let's get into a simple example of connecting the Astro framework with Hygraph using the microblog starter from the marketplace:

- <Link href="https://app.hygraph.com/clone/17eb970b42d544c595b5772ba3614551?name=Microblog" target="_blank">Clone the Hygraph project</Link>
- <Link href="https://github.com/hygraph/hygraph-astro-microblog-starter" target="_blank">Get the Astro code from Github</Link>

Or you can clone the Astro microblog by typing the following command in your terminal:

```
npx degit git@github.com:hygraph/hygraph-astro-microblog-starter.git
```

Navigate to the project directory and type `npm install` to install the package dependencies by typing the following command:

```
cd hygraph-astro-microblog-starter && npm install
```

Once the installation process is finished, create a `.env` file in the root directory and the `ASTRO_HYGRAPH_ENDPOINT` variable with a link to your API endpoint from Hygraph.

Run the command `npm run dev` and your microblog will be available in the browser via localhost:

![Astro - localhost](/images/docs/implementations/astro/astro-localhost.png)

<Alert theme="info" title="Pro Tip">
Your assigned localhost port number may vary depending on your environment, but the assigned port and the link will be available to you in the terminal.
</Alert>

Your microblog is now available locally via localhost at `http://localhost:NUMBER-IN-YOUR-TERMINAL`!

![Astro - microblog](/images/docs/implementations/astro/astro-microblog.png)

### Code overview

Now that we have our Hygraph project and Astro frontend up and running, let's take a quick dive into the code of the starter.

#### Hygraph endpoint GraphQL queries for posts

The fragments directory in your Astro code contains two GraphQL fragments:

```js
export const postsFragment = `
pageInfo {
    hasNextPage
    endCursor
}
postsArray: edges {
    cursor
    post: node {
        slug
        id
        createdAt
        content {
            html
        }
    }
}`;

export const postFragment = `
id
slug
content {
    html
}
createdAt
`;
```

The `postsFragment` is used to fetch information about a list of posts to implement the <Link href="https://hygraph.com/blog/lazy-load-content-astro-hygraph-pagination" target="_blank">lazy load pagination feature</Link> of the microblog.

The `postFragment` is used to fetch information about each post to render on individual pages.

#### Individual post pages

To create the individual blog post pages, we are using the `getStaticPaths` function, an Astro helper function that's used to generate static paths for each blog post.

This function fetches data from a GraphQL endpoint (specified by `ASTRO_HYGRAPH_ENDPOINT` environment variable) using a `POST` request. The request body contains a GraphQL query that fetches posts using the `postFragment`:

```js
---
import Main from "../../layouts/Main.astro";
import Post from "../../components/Post.astro";
import { postFragment } from "../../../fragments/posts";

//export getstaticpaths
export async function getStaticPaths() {
  const response = await fetch(
    import.meta.env.ASTRO_HYGRAPH_ENDPOINT,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        query: `query MyQuery() {
          posts() {
              ${postFragment}
          }
        }
        `,
      }),
    }
  );

  const json = await response.json();

  const paths = json.data.posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }));

  return paths;
}

const {post} = Astro.props
---

<Main title="My Microblog">
  <div>

    <Post post={post} />

  </div>
</Main>
```

The above code generates individual post pages with their respective content:

![Astro - individual post pages](/images/docs/implementations/astro/astro-individual-post-pages.png)

Individual post pages will contribute to a more organized, engaging, and user-friendly microblog.

<Alert theme="info" title="Pro Tip">
For more Astro implementations, <Link href="https://github.com/hygraph/skncre-starter-astro" target="_blank">check out our Astro Skncre starter!</Link>
</Alert>


---
# Hygraph resources for Astro

Source: https://hygraph.com/docs/implementations/astro/resources

Here's a list of our resources for Astro:

| Resource name                                                                                                                              | Resource type                | Description                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/blog/lazy-load-content-astro-hygraph-pagination" target="_blank">Implementing lazy load content with Astro.js and Hygraph pagination</Link> | Blog post                    | Learn how to load a set of posts as static HTML created during the site build and then implement a load more button in React to query Hygraph for more content and load that onto the page. |
| <Link href="https://www.youtube.com/watch?v=8FYvmFSKtC4" target="_blank">Implementing lazy load content with Astro.js and Hygraph pagination</Link>                         | Video                        | Learn how to load a set of posts as static HTML created during the site build and then implement a load more button in React to query Hygraph for more content and load that onto the page. |
| <Link href="https://www.youtube.com/watch?v=O_dVLRWPeBk" target="_blank">Pagination with Astro and Hygraph</Link>                                                           | Video - Livestream recording | Our Devrels Bryan and Tim show how to asynchronously load more content via pagination or a load more button.                                                                                |
| <Link href="https://www.youtube.com/watch?v=AieTLJMxmxM" target="_blank">Building an e-commerce site with Hygraph and Astro</Link>                                          | Video - Livestream recording | Livestream where we convert the **Skncre** Nuxt starter for Hygraph to Astro. Along the way you will learn the core concepts of Astro and Hygraph, all while diving deep into the code.     |


---
# Hygraph snippets for Astro

Source: https://hygraph.com/docs/implementations/astro/snippets

Here's a list of our snippets for Astro. Each snippet links to you the repo:

| Snippet name                                                                | Description                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-astro" target="_blank">Astro</Link> | Example snippet that shows how to use the Astro with Hygraph. |

---
# Hygraph starters for Astro

Source: https://hygraph.com/docs/implementations/astro/starters

Here's a list of our starters for Astro. Each starter links to you their Marketplace page:

| Starter name                                                                | Description                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------ |
| <Link href="https://hygraph.com/marketplace/starters/astro-microblog" target="_blank">Astro Microblog</Link> | A microblog using Astro.js, Tailwind CSS, and Hygraph. |
| <Link href="https://hygraph.com/marketplace/starters/skncre-starter-astro" target="_blank">SKNCRE</Link>     | A composable cosmetics e-commerce demo Hygraph, Astro, and an external API for product data.|


---
# Flutter + Hygraph

Source: https://hygraph.com/docs/implementations/flutter/flutter

## Overview

<Link href="https://flutter.dev/" target="_blank">Flutter</Link> is a cross-platform software development kit (SDK) for mobile app development that uses Dart programming language to create apps for Android and iOS devices.

### Prerequisites

To follow along, the following prerequisites are required.

- <Link href="https://docs.flutter.dev/get-started/install" target="_blank">Flutter SDK</Link> and all of its dependencies installed on your machine
- Basic knowledge of <Link href="https://dart.dev/language" target="_blank">Dart programming language</Link>
- A <Link href="https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes" target="_blank">iOS simulator</Link> and/or <Link href="https://developer.android.com/studio" target="_blank">Android studio</Link> installed on your machine


## Creating a new Flutter app

This guides covers how to connect a Flutter application to Hygraph and query content using a GraphQL client. To create a new Flutter app, run the following command:

```bash
flutter create <PROJECT_NAME_HERE>
```
## Getting data from Hygraph

Let's practice getting data from Hygraph. Start by cloning our blog app Hygraph project:

<Button
  href="https://app.hygraph.com/clone/ddebd4bb62d042c1b9e85e75e9708fcf?name=Blog%20App%20-%20Flutter%20Implementation%20Guide"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Click here to clone the project</Button>

After cloning, you will have a simple project that contains a few basic content models that would typically be used in a blog. The **Post** model contains fields such a `title`, `excerpt`, `authorName`, and `coverImage` and three sample blog posts in the **Content** section.

## Content API

Before you can connect Flutter to Hygraph, you will need to configure **Content API** access permissions for unauthenticated requests.

To do this, go **Project settings > Access > API Access > Content API** in your Hygraph project, scroll to find the **Content Permissions** box that reads **Would you like us to initialize some defaults?**, and click `Yes, initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, copy the `High Performance Content API` endpoint from **Project settings > Access > API Access > Endpoints**. You use it to connect Flutter to Hygraph later on.

## Testing a query in the API playground

Next, you should test if you can fetch the information from the sample blog posts in your project. To do this, navigate to the API Playground in your project and use the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

  ```graphql
    query Posts {
      posts {
        id
        title
        slug
        author {
          name
        }
      }
    }
  ```
  </TabsItem>
  <TabsItem label="Response">

  ```json
  {
    "data": {
      "posts": [
        {
          "id": "clxywncre19wz07k5qot81kk7",
          "title": "Hygraph works with any framework!",
          "slug": "hygraph-any-framework",
          "author": {
            "name": "Lo Etheridge"
          }
        },
      ]
    }
  }
  ```
  </TabsItem>
</Tabs>

If you execute the query, the response should fetch all the sample blog posts in the demo project you cloned.

## Connecting Flutter to Hygraph

To practice connecting Hygraph to Flutter, clone the basic blog flutter app from our repository using the following command:

  ```bash
npx degit https://github.com/hygraph/flutter-hygraph-blog.git
  ```

### Installing graph_flutter
After cloning the blog app, navigate to the root of your project `cd flutter-hygraph-blog` to add the `graph_flutter` package to your Flutter project. This package provides a set of widgets that make it easy to run queries and mutations with our content from  Hygraph in our Flutter project.

To install the GraphQL package, type the following command in the root directory of your Flutter project:
```dart
flutter pub add graphql_flutter
```

### Configuring the GraphQL client

After the installation completes, import the package in the `lib/main.dart` file, using the following code:

```dart
// File location: lib/main.dart
import 'package:graphql_flutter/graphql_flutter.dart';
```

Now, we can use the `GraphQLClient()` widget and Hygraph content API endpoint URL you copied earlier from your Hygraph project. Add the the endpoint URL to the `HttpLink()` variable and pass it to the
`GraphQLClient()` widget in the `lib/main.dart` file:

```dart
// File location: lib/main.dart
final HttpLink httpLink = HttpLink("https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master");

final ValueNotifier<GraphQLClient> client = ValueNotifier<GraphQLClient>(
  GraphQLClient(
    link: httpLink,
    cache: GraphQLCache(),
  ),
);
```
That's it! You have successfully connected your Flutter app to Hygraph. You can now run queries and mutations to fetch content from your Hygraph project.

## Running a Posts query in Flutter
Let's run a query to fetch all the blog posts from your Hygraph project. Add the following code to your `lib/main.dart` file just below your Hygraph GraphQL client configuration:

```dart
// File location: lib/main.dart
const String query = """
query Posts{
  posts{
    id
    publishedAt
    title
    excerpt
    coverImage {
      url
    }
    author {
      id
      name
    }
  }
}
""";
```
The above query fetches all blog posts from Hygraph and their field content such as `id`, `publishedAt`, `title`, `excerpt`, `coverImage`, and `author`. The great thing about GraphQL is that it allows you to query only the fields you need, which makes your queries faster and more efficient. This makes a difference with any application, but is especially important in mobile applications where data usage and speed are critical.

## Displaying the posts in a Flutter app

Your cloned Flutter app contains a directory called `widgets` that contains a `blog_row.dart` file that creates a `BlogRow` widget for displaying the blog posts from Hygraph.

The `BlogRow` widget is a `StatelessWidget` that fetches the blog posts from Hygraph and displays them in a `ListView` widget. In other words, it's a simple widget that displays the blog posts in a list that we can import and use in our `main.dart` file.

Next, import the `BlogRow` widget in your `lib/main.dart` file and add the following code to display the blog posts in your Flutter app:

```dart
// File location: lib/main.dart
import 'widgets/blog_row.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return GraphQLProvider(
      client: client,
      child: MaterialApp(
          title: 'GraphQL Demo',
          theme: ThemeData(
            primarySwatch: Colors.blue,
          ),
          home: Scaffold(
            appBar: AppBar(
              title: const Text(
                "Hygraph blog app using Flutter",
              ),
            ),
            body: Query(
                options: QueryOptions(
                    document: gql(query),
                    variables: const <String, dynamic>{"code": "AF"}),
                builder: (result, {fetchMore, refetch}) {
                  if (result.isLoading) {
                    return const Center(
                      child: CircularProgressIndicator(),
                    );
                  }
                  if (result.data == null) {
                    return const Center(
                      child: Text("No article found!"),
                    );
                  }
                  final posts = result.data!['posts'];
                  return ListView.builder(
                    itemCount: posts.length,
                    itemBuilder: (context, index) {
                      final post = posts[index];
                      final title = post['title'];
                      final excerpt = post['excerpt'];
                      final coverImageURL = post!['coverImage']['url'];
                      final authorName = post['author']['name'];
                      return BlogRow(
                        title: title,
                        excerpt: excerpt,
                        coverURL: coverImageURL,
                        authorName: authorName,
                      ); // BlogRow widget
                    },
                  ); // ListView.builder
                }), // Query
          )), // MaterialApp
    ); // GraphQLProvider
  }
}
```
### Code overview

The above code uses the returned content that we fetched from our blog posts query to display posts in a scrollable list using the `ListView.builder` widget. The `BlogRow` widget is used to display each blog post in the list.

## Putting all the Flutter pieces together
We have all these pieces we need to create the `Main` widget or entry point of our Flutter app. Your `lib/main.dart` file should have the following code and structure:

```dart
// File location: lib/main.dart
import 'widgets/blog_row.dart';
import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';

void main() {
  runApp(const MyApp());
}

// Create GraphQL client and connect to Hygraph content API
final HttpLink httpLink = HttpLink(
    "https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master");

final ValueNotifier<GraphQLClient> client = ValueNotifier<GraphQLClient>(
  GraphQLClient(
    link: httpLink,
    cache: GraphQLCache(),
  ),
);

// GraphQL query to fetch all blog posts
const String query = """
query Posts{
  posts{
    id
    publishedAt
    title
    excerpt
    coverImage {
      url
    }
    author {
      id
      name
    }
  }
}
""";

// Main widget
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return GraphQLProvider(
      client: client,
      child: MaterialApp(
          title: 'GraphQL Demo',
          theme: ThemeData(
            primarySwatch: Colors.blue,
          ),
          home: Scaffold(
            appBar: AppBar(
              title: const Text(
                "Hygraph blog app using Flutter",
              ),
            ),
            body: Query(
                options: QueryOptions(
                    document: gql(query),
                    variables: const <String, dynamic>{"code": "AF"}),
                builder: (result, {fetchMore, refetch}) {
                  if (result.isLoading) {
                    return const Center(
                      child: CircularProgressIndicator(),
                    );
                  }
                  if (result.data == null) {
                    return const Center(
                      child: Text("No article found!"),
                    );
                  }
                  final posts = result.data!['posts'];
                  return ListView.builder(
                    itemCount: posts.length,
                    itemBuilder: (context, index) {
                      final post = posts[index];
                      final title = post['title'];
                      final excerpt = post['excerpt'];
                      final coverImageURL = post!['coverImage']['url'];
                      final authorName = post['author']['name'];
                      return BlogRow(
                        title: title,
                        excerpt: excerpt,
                        coverURL: coverImageURL,
                        authorName: authorName,
                      );
                    },
                  );
                }),
          )),
    );
  }
}
```
With everything in it's right place, you can now run your Flutter app using the following command:

```bash
flutter run
```
With Flutter running, your app should feature a list of blog posts, like so:

### Native iOS app
![Flutter iOS app](/images/docs/implementations/flutter/flutter-hygraph-iosapp.png)

### Web app
![Flutter web app](/images/docs/implementations/flutter/flutter-hygraph-webapp.png)

Congratulations, you now have a Flutter Blog app that shows posts from Hygraph that is available to run cross-platform on iOS and Android devices as well as in a browser!

<Alert theme="info" title="Pro Tip">
This was a simple and quick example of how to fetch and render content from Hygraph ina Flutter app.

For more complete implementation examples, [follow a Flutter guide ](/docs/implementations/flutter/resources).
</Alert>



---
# Hygraph resources for Flutter

Source: https://hygraph.com/docs/implementations/flutter/resources

Here's a list of our resources for Flutter:

| Resource name                                                                                                                              | Resource type                | Description                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/blog/hygraph-for-fluttering-parrotheads" target="_blank">Hygraph for Fluttering Parrotheads</Link>                                          | Blog post                    | Learn how to create a Jimmy Buffett Fan Club app in Flutter, powered by Hygraph.                                                                                           |
| <Link href="https://hygraph.com/blog/build-dynamic-flutter-apps" target="_blank">How to build dynamic Flutter apps with Hygraph</Link>                                      | Blog post                    | Learn how to build a news app in Flutter with Hygraph.                                                        |
| <Link href="https://hygraph.com/blog/flutter-graphql" target="_blank">Guided tutorial on how to use GraphQL with Flutter</Link>                                             | Blog post                    | Learn how to create a simple app that consumes a Hygraph endpoint in a Flutter application. |



---
# Hygraph starters for Flutter

Source: https://hygraph.com/docs/implementations/flutter/starters

Here's a list of our starters for Flutter.

| Starter name                                                                | Description                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------ |
| <Link href="https://github.com/hygraph/flutter-hygraph-blog" target="_blank">Basic Blog App</Link> | A basic blog app starter for cross-platform development using Hygraph.  |


---
# Implementations

Source: https://hygraph.com/docs/implementations/index

This section contains information on how to do frontend implementations with different Frameworks.

<CardGrid columns='3' gap='sm' className="!px-0">
  <BorderedCard
    title="Astro"
    href="/docs/implementations/astro/astro"
  />
  <BorderedCard
    title="Flutter"
    href="/docs/implementations/flutter/flutter"
  />
  <BorderedCard
    title="Next"
    href="/docs/implementations/next/next"
  />
  <BorderedCard
    title="Nuxt"
    href="/docs/implementations/nuxt/nuxt"
  />
  <BorderedCard
    title="Remix"
    href="/docs/implementations/remix/remix"
  />
  <BorderedCard
    title="SvelteKit"
    href="/docs/implementations/sveltekit/sveltekit"
  />
</CardGrid>

<Alert theme="info" title="Do you have suggestions?">

If you want to suggest that we add a framework implementation guide to our docs, <Link href="https://hygraph-community.slack.com" target="_blank">join our community and share it in the Feedback channel!</Link>

</Alert>

## Content API

Before we can connect the framework of our choice to Hygraph, we will need to configure **Content API** access permissions for unauthenticated requests.

To do this, we'll to go **Project settings > Access > API Access > Content API** in our Hygraph project, scroll to find the **Manage Content API access permissions** box and click `Initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, we will copy the `High Performance Read-only Content API` endpoint from **Project settings > Access > API Access > Endpoints**. We will use it to connect our framework to Hygraph later on.

## Resources

This section offers a list of resources you can use:

| Framework   | Implementation guide                                          | Official starter                                                                              | Additional resources                                                                                                                                                                 |
| ----------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Astro`     | [Connection guide](/docs/implementations/astro/astro)         | [Microblog starter](/docs/implementations/astro/microblog-astro)                              | [Starters](/docs/implementations/astro/starters) <br></br> [Snippets](/docs/implementations/astro/snippets) <br></br> [Resources](/docs/implementations/astro/resources)             |
| `Flutter`   | [Connection guide](/docs/implementations/flutter/flutter)     | <Link href="https://github.com/hygraph/flutter-hygraph-blog" target="_blank">Basic Blog App</Link>                             | [Starters](/docs/implementations/flutter/starters)<br></br> [Resources](/docs/implementations/sveltekit/resources)                                                                   |
| `Next`      | [Connection guide](/docs/implementations/next/next)           | [Hygraphlix starter](/docs/implementations/next/hygraphlix-next)                              | [Starters](/docs/implementations/next/starters) <br></br> [Snippets](/docs/implementations/next/snippets) <br></br> [Resources](/docs/implementations/next/resources)                |
| `Nuxt`      | [Connection guide](/docs/implementations/nuxt/nuxt)           | [Skncre starter](/docs/implementations/nuxt/skncre-nuxt)                                      | [Starters](/docs/implementations/nuxt/starters) <br></br> [Snippets](/docs/implementations/nuxt/snippets) <br></br> [Resources](/docs/implementations/nuxt/resources)                |
| `Remix`     | [Connection guide](/docs/implementations/remix/remix)         | <Link href="https://hygraph.com/marketplace/starters/hygraph-remix-documentation" target="_blank">Documentation starter</Link> | [Starters](/docs/implementations/remix/starters) <br></br> [Snippets](/docs/implementations/remix/snippets) <br></br> [Resources](/docs/implementations/remix/resources)             |
| `SvelteKit` | [Connection guide](/docs/implementations/sveltekit/sveltekit) | <Link href="https://hygraph.com/marketplace/starters/hygraph-sveltekit-portfolio" target="_blank">Developer Portfolio</Link>   | [Starters](/docs/implementations/sveltekit/starters) <br></br> [Snippets](/docs/implementations/sveltekit/snippets) <br></br> [Resources](/docs/implementations/sveltekit/resources) |



---
# HYGRAPHlix starter + Next

Source: https://hygraph.com/docs/implementations/next/hygraphlix-next

## Overview

Use our HYGRAPHlix starter with Next.js to create a streaming platform.

## Quickstart: Clone the Hygraphlix Next starter

To get up and running quickly with Next and Hygraph, clone **Hygraphlix**, a composable movie platform starter:
1. <Link href="https://app.hygraph.com/clone/60a5f60969474157a5bb6cec6452e833?name=Hygraph%20Movie%20Platform%20Starter" target="_blank">Clone the Hygraph project</Link>
2. <Link href="https://github.com/lowisren/hygraph-movie-starter" target="_blank">Get the Next code from Github</Link>

Install Hygraphlix via terminal:

```
npx degit https://github.com/lowisren/hygraph-movie-starter/
```

Alternatively, <Link href="https://app.hygraph.com/" target="_blank">you can clone <strong>Hygraphlix</strong> from the Hygraph project directory</Link> from the selection of available starters.

<Alert theme="info" title="Starter recap">

All Hygraph starters are located on the project directory after to login.

Scroll past the “My Projects” section to the “Start a new Project” section and choose the **Hygraphlix** starter. This will create a new hygraph project as well as the frontend template for a website.

</Alert>

### Connecting Hygraph to Next

Change directory to your new **Hygraphlix-Next** project run `npm install` to install dependencies.

[After initializing permissions](/docs/implementations#content-api), we'll create a `.env` file by renaming the .`env.example` file in the root of our Next project.

Add [the endpoint URL we copied from Hygraph](/docs/implementations#content-api) inside the `.env` file:

```
HYGRAPH_ENDPOINT=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```

### Configure Hygraph assets to work with Next

To work with Next image module, you need to specify Hygraph as an image domain by adding the domain URL in the `next.config.js` file. The Hygraphlix starter uses Hygraph as well as several other image sources. You can add additional image hosts as needed to the `remotePatterns` array in the Next config file, like so:

```js
// next.config.js for Hygraphlix starter
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    dangerouslyAllowSVG: true,
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'media.graphassets.com'
      },
      {
        protocol: 'https',
        hostname: 'm.media-amazon.com'
      },
   {
   protocol: 'https',
   hostname: 'vercel.com'
   },
          ]
    },
}
module.exports = nextConfig
```

Run `npm run dev` to initialize the app, your site will be available in the browser at `http://localhost:3000/`.

![HYGRAPHlix](/images/docs/implementations/next/hygraphlix.png)

Thats it! your Hygraph project is now connected to Next!

<Alert theme="info" title="Pro Tip">
For more Next implementations, check out our <Link href="https://hygraph.com/marketplace/starters/hygraph-next-commerce-starter" target="_blank">Next e-commerce starter</Link> or the <Link href="https://github.com/hygraph/hygraph-next-microblog-starter" target="_blank">Next Microblog starter</Link> from the project directory.
</Alert>


---
# Next + Hygraph

Source: https://hygraph.com/docs/implementations/next/next

## Overview

<Link href="https://nextjs.org/" target="_blank">Next.js</Link> is a React framework that you can use to create high-quality web applications powered by React components.

## Creating a new Next app

Start by initializing a new `Next.js 14` project. Open up your terminal, navigate to where you want your project, and run the following command:

```bash
npx create-next-app my-next-project

```

The interactive setup will ask you questions to configure your project. Initialize with the following answers:
- **Typescript:** No
- **ESLint:** Yes
- **Tailwind CSS:** Yes
- **src/ directory:** No
- **App Router:** Yes
- **Import alias:** No

After choosing the options, the CLI will install all the necessary pieces to run your `Next.js` site.

Once the installation completes, open the new Next project in a code editor of your choice.

You need to adjust the default Tailwind styling that `Next.js` gives us from the installation. To do this, remove the global CSS rules in `app/globals.css` except the following Tailwind imports:

```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

Change directory to your new Next project run `npm install` to install dependencies:

```
cd my-next-project && npm install
```

Run the command  `npm run dev` to initialize the app. Your site will be available in the browser at `http://localhost:3000/`.

![Next](/images/docs/implementations/next/nextjs-locally.png)

### Configure Hygraph assets to work with Next

To work with Next image module, you need to specify Hygraph as an image domain by adding the domain URL in the `next.config.js` file.

Your config file should contain the following code:

```js
// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    dangerouslyAllowSVG: true,
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.graphassets.com',
      },
     ]
    },
}
module.exports = nextConfig
```

## Getting data from Hygraph

Now that you have created your Next project, it's time to add some data from Hygraph. Start by cloning our demo Hygraph project:

<Button
  href="https://app.hygraph.com/clone/751a6bdf9431476c8b82c543895e6d16?name=Implementation%20Guides"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Click here to clone the demo project</Button>

After cloning, you will have a simple project that contains one content model called **Page** that contains fields for `Title`, `Slug`, and `Body`; and one content entry.

If you navigate to the Schema builder and click on the **Page** model, you will see this:

![Demo project - Page model](/images/docs/implementations/demo-project-page-model.png)

And if you navigate to the Content editor and view the sample entry details, you'll see this:

![Demo project - Sample content entry](/images/docs/implementations/demo-project-sample-entry.png)

## Content API

Before you can connect Next to Hygraph, you will need to configure **Content API** access permissions for unauthenticated requests.

To do this, we'll to go **Project settings > Access > API Access > Content API** in our Hygraph project, scroll to find the **Manage Content API access permissions** box and click `Initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, we will copy the `High Performance Read-only Content API` endpoint from **Project settings > Access > API Access > Endpoints**. You will use it to connect Next to Hygraph later on.

## Testing a query in the API playground

Next, you should test if you can fetch the information in the sample content entry that we showed you earlier. To do this, navigate to the API Playground in your project and use the following query:

<Tabs panelHeight={280}>
  <TabsItem label="Query">

```graphql
query Page {
  page(where: {slug: "hygraph-works-with-any-framework"}) {
    title
    body {
      text
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "page": {
      "title": "Hygraph works with any framework!",
      "body": {
        "text": "No matter the framework you choose, Hygraph is there for you and all your content needs. "
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

If you execute the query, the response should fetch the sample query in the demo project you cloned.

Want to see Next and Hygraph in action? Watch a quick video on how to connect `Next` and `Hygraph`:
<VideoEmbed videoId="fkSW0BFbtdo"/>

## Generating Hygraph content with Next

[After enabling API access](/docs/implementations/next/next#content-api), you can start using the **Pages** query with your Next app to render content.

Create an `.env` file in the root of your Next project. Add the endpoint URL you copied from Hygraph inside the `.env` file, like this:

```
NEXT_HYGRAPH_ENDPOINT=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```
### Getting a list of pages for the homepage

After adding your `.env` file, go to your `page.js` file in the app directory and replace its contents with the following code:

<Tabs panelHeight={280}>
  <TabsItem label="JavaScript">
```js
// file: app/page.js
// get a list of pages from hygraph
import Link from "next/link";

async function getPages() {
  const NEXT_HYGRAPH_ENDPOINT = process.env.NEXT_HYGRAPH_ENDPOINT;
  const response = await fetch(NEXT_HYGRAPH_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `query Pages {
                pages {
                  title
                  slug
                  body {
                    text
                  }
                }
              }`,
    }),
  });
  const json = await response.json();
  return json.data.pages;
}
export default async function Home() {
  const pages = await getPages();
  //console.log(pages);
  return (
    <div className="m-12">
      <h1 className="text-5xl font-bold mb-4">
        Hygraph Implementation Guides demo
      </h1>
      <p className="text-lg mb-4">Click the links below to see other pages</p>
      <ul className="mb-8 list-disc list-inside">
        {pages.map((page) => {
          return (
            <li key={page.slug}>
              <Link href={`/page/${page.slug}`} className="underline">
                {page.title}
              </Link>
            </li>
          );
        })}
      </ul>
      <p>
        <button
          className="bg-indigo-500 hover:bg-indigo-700 text-white font-bold py-2 px-4 my-2 rounded">
          <Link
            href="https://hygraph.com/docs/implementations"
            target="_blank">Implementation Docs</Link>
        </button>
      </p>
    </div>
  );
}
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// file: app/page.tsx
// get a list of pages from hygraph
import Link from "next/link";

async function getPages() {
  const response = await fetch(process.env.NEXT_HYGRAPH_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `query Pages {
        pages {
          title
          slug
          body {
            text
          }
        }
      }`,
    }),
  });
  const json = await response.json();
  return json.data.pages;
}
export default async function Home() {
  const pages = await getPages();
  return (
    <div className="m-12">
      <h1 className="text-5xl font-bold mb-4">
        Hygraph Implementation Guides demo
      </h1>
      <p className="text-lg mb-4">Click the links below to see other pages</p>
      <ul className="mb-8 list-disc list-inside">
        {pages.map((page: any) => {
          return (
            <li key={page.slug}>
              <Link href={`/page/${page.slug}`} className="underline">
                {page.title}
              </Link>
            </li>
          );
        })}
      </ul>

      <p>
        <a
          className="bg-indigo-500 hover:bg-indigo-700 text-white font-bold py-2 px-4 my-6 rounded"
          href="https://hygraph.com/docs/implementations"
          target="_blank"
        >
          Implementation Docs
        </a>
      </p>
    </div>
  );
}
```
</TabsItem>
</Tabs>

#### Code overview

In the above code, we have created the function `getPages()` that queries and fetches all pages from Hygraph. The `Home` function calls the `getPages` function and waits for the query to return with our content from Hygraph. Then, we use our content to  render a list of links to other pages and added a button that will bring you back to this guide.

![Homepage](/images/docs/implementations/next/next-homepage.png)

### Creating dynamic page routes with Next

Now, that we have a list of pages in our homepage, we need to create a dynamic route for each page. To do this, create a new directory in the `app` directory called `pages/[slug]` and a file called `page.js` inside the new directory. Once created add following code:

<Tabs panelHeight={280}>
  <TabsItem label="JavaScript">
```js
// file: app/page/[slug]/page.js
// get page content from hygraph and create a new page for each new slug
import Link from "next/link";
async function getPage(slug) {
    const NEXT_HYGRAPH_ENDPOINT = process.env.NEXT_HYGRAPH_ENDPOINT;
  const response = await fetch(NEXT_HYGRAPH_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `query Page($slug:String!) {
        page(where: {slug: $slug}) {
          title
          slug
          body {
            text
          }
        }
      }`,
      variables: {
        slug,
      },
    }),
  });
  const json = await response.json();
  return json.data.page;
}
export default async function Page({ params }) {
  const page = await getPage(params.slug);
  return (
    <div className="m-12">
      <h1 className="text-5xl font-bold mb-4">{page.title}</h1>
      <p className="text-lg mb-8">{page.body.text}</p>

      <p>
        <Link href="/" className="underline">
          Back to homepage
        </Link>
      </p>
    </div>
  );
}
```
</TabsItem>
  <TabsItem label="TypeScript">
```ts
// file: app/page/[slug]/page.tsx
// get page content from hygraph and create a new page for each new slug
import Link from "next/link";

async function getPage(slug: string) {
  const response = await fetch(process.env.NEXT_HYGRAPH_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `query Page($slug:String!) {
        page(where: {slug: $slug}) {
          title
          slug
          body {
            text
          }
        }
      }`,
      variables: {
        slug,
      },
    }),
  });
  const json = await response.json();
  return json.data.page;
}

export default async function Page({ params }: { params: { slug: string } }) {
  const page = await getPage(params.slug);
  return (
    <div className="m-12">
      <h1 className="text-5xl font-bold mb-4">{page.title}</h1>
      <p className="text-lg mb-8">{page.body.text}</p>

      <p>
        <Link href="/" className="underline">
          Back to homepage
        </Link>
      </p>
    </div>
  );
}
```
  </TabsItem>
</Tabs>

#### Code overview

In the above code, we are taking advantage of the dynamic routing capabilities of the Next app router to create a page route,`http://localhost:3000/page/{page.slug}`, that makes new page for every `slug`. The `Page()` function calls the `getPage` function and waits for the query to return with our content from Hygraph. Then, we use our content to render the page title and body text, and added a button that will bring you back to the homepage.

![Dynamic page](/images/docs/implementations/next/next-dynamic-page.png)

Congratulations! You have a homepage and a dynamic page route to render all pages and their content.

<Alert theme="info" title="Pro Tip">
This was a simple and quick example of how to fetch and render content from Hygraph using Next.

For more complete implementation examples, <Link href="https://app.hygraph.com/" target="_blank">clone a starter</Link>.
</Alert>


---
# Hygraph resources for Next

Source: https://hygraph.com/docs/implementations/next/resources

Here's a list of our resources for Next:

| Resource name                                                                                                            | Resource type                | Description                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-next-commerce-starter" target="_blank">Next 14 eCommerce starter</Link>                      | Hygraph Marketplace page     | A simple eCommerce experience using Next.js, TailwindCSS, a custom reviews API, and Hygraph as a PIM.                                                                                                                |
| <Link href="https://hygraph.com/blog/hygraphfm-building-artist-schema-remote-source" target="_blank">Hygraph FM: Building the artist content model</Link> | Blog post                    | Learn how to build an artist content model for the music streaming platform Hygraph FM, add the LastFM Rest API as a remote source to retrieve metadata, and create a modular component to structure artist content. |
| <Link href="https://hygraph.com/blog/building-artist-page-components-hygraphfm" target="_blank">Hygraph FM: Building an artist page with components and Next</Link>   | Blog post        | Learn how to build Leran how to build a frontend with Next and use remote LastFM date for landing pages                                                                                                              |
| <Link href="https://hygraph.com/blog/adding-pagination-seo-hygraphfm" target="_blank">Hygraph FM: Adding pagination with Next.js and maintaining SEO</Link>                 | Blog post  | Learn how to how to add pagination and maintain SEO using Hygraph and Next                                                                                                                                                         |
| <Link href="https://www.youtube.com/watch?v=t00uXBjsDUM" target="_blank">Bryan teaches Tim Next.js with GraphQL and Hygraph</Link>                        | Video - Livestream recording | See Tim learn on the spot as Bryan teaches him Next.js 14 app directory with GraphQL and "load more" functionality with Hygraph.                                                                                     |
| <Link href="https://www.youtube.com/watch?v=HS1iMXycyqg" target="_blank">Creating an Enterprise News starter with Next.js and Hygraph CMS</Link>          | Video - Livestream recording | Dive into this enterprise-ready content starter that will accelerate your Hygraph project's development, enhance user engagement, and unlock new possibilities.                                                      |
| <Link href="https://www.youtube.com/watch?v=LnfRLXHVUNA" target="_blank">Creating a QR Code Custom Sidebar Element with Next.js in Hygraph</Link>         | Video                        | Extending the functionality of your CMS is incredibly important. The ability to add features for your editors while maintaining developer experience is paramount to creating great workflows in your company.       |



---
# Hygraph snippets for Next

Source: https://hygraph.com/docs/implementations/next/snippets

Here's a list of our snippets for Next. Each snippet links to you the repo:

| Snippet name                                                                                          | Description                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextauth-credentials" target="_blank">Next Auth</Link>        | This example demonstrates how to query from Hygraph `NextAuth.js`.                                                                                                                                                                 |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-app-directory" target="_blank">Next App Router</Link>  | This example demonstrates how to query from Hygraph with `graphql-request` in `Next.js`.                                                                                                                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-i18n-routing" target="_blank">Next i18n Routing</Link> | This example demonstrates how to use `Next.js` Internationalized Routing with localized Hygraph content.                                                                                                                           |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-image" target="_blank">Next Image</Link>               | This example demonstrates how to use the `Next.js` Image Component with your Hygraph assets.                                                                                                                                       |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-image-loader" target="_blank">Next Image Loader</Link> | This example demonstrates how to use a custom loader function with `Next.js` Image Component and Hygraph assets. This allows you to perform asset transformations using the Hygraph CDN, rather than the default `Next.js` loader. |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs-mdx-remote" target="_blank">Next mdx remote</Link>     | This example demonstrates how to use markdown fields from Hygraph with `MDX` in `Next.js`.                                                                                                                                         |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nextjs" target="_blank">NextJs</Link>                         | This example demonstrates how to query from Hygraph with `graphql-request` in `Next.js`.                                                                                                                                           |


---
# Hygraph starters for Next

Source: https://hygraph.com/docs/implementations/next/starters

Here's a list of our starters for Next. Each starter links to you their Marketplace page:

| Starter name                                                                                        | Description                                                                                                                                  |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/marketplace/starters/next-microblog" target="_blank">Next.js Microblog</Link>                        | A microblog using Next.js, Tailwind CSS, and Hygraph.                                                                                        |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-next-commerce-starter" target="_blank">Next 14 eCommerce starter</Link> | A simple eCommerce experience using Next.js, TailwindCSS, a custom reviews API, and Hygraph as a PIM.                                        |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-nextjs-mux-movie-platform" target="_blank">Hygraphlix</Link>            | Use our movie starter to create a movie streaming platform with Hygraph, Next, and Mux.                                                                          |
| <Link href="https://hygraph.com/marketplace/starters/skncre-starter-next" target="_blank">SKNCRE</Link>                              | A composable cosmetics e-commerce demo with Hygraph, Next, and an external API for product data.      |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-nextjs-nextauth-swr-todo" target="_blank">To-Do App</Link>              | Simple to-do app built with Hygraph, Next.js, Next/Auth, and SWR, focused on user-generated content with task management.                    |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-nextjs-chakra-website" target="_blank">Marketing Website</Link>         | Marketing website focused on selling subscription-based SaaS products, built using Hygraph, Next.js, and Chakra UI.                          |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-nextjs-storefront" target="_blank">eCommerce Storefront</Link>          | Simple eCommerce shop built using Next.js, TailwindCSS, Stripe, and Hygraph, focused on order creation and checkout, using Hygraph as a PIM. |


---
# Nuxt + Hygraph

Source: https://hygraph.com/docs/implementations/nuxt/nuxt

## Overview

<Link href="https://nuxt.com/" target="_blank">Nuxt</Link> is a free, open-source Vue framework. You can use it to create type-safe, performant and production-grade full-stack web applications and websites intuitively.

## Creating a new Nuxt app

To start, we need to initialize a new `Nuxt` project. Open up your terminal, navigate to where you want your project, and run the following command:

```bash
npx nuxi@latest init my-nuxt-project
```

The interactive setup will ask you questions to configure your project. Initialize with the following answers:
- **Current nuxt version, Ok to proceed:** Yes (y)
- **Choose package manager:** npm, pnpm, yarn, or bun (the guide will use yarn)
- **Anonymous usage data collection:** Yes or No
- **Initial git repository:** Yes or No

Change directory into your new project from your terminal:

```
cd my-nuxt-project
```

The interactive setup should install dependencies automatically using the package manager - yarn, pnpm, npm - of your choosing, but you can use the install command if needed:

```
npm install
```

Start your Nuxt app in development mode:

```
npm run dev
```

Your new Nuxt app is now available in the browser at `http://localhost:3000/`

![Nuxt](/images/docs/implementations/nuxt/nuxt-locally.png)

### Configure Hygraph assets to work with Nuxt

To work with Nuxt image module, we need to specify Hygraph as an image provider by adding the base URL in the `nuxt.config.ts` file.

Your config file should contain the following code:

```js
// nuxt.config.ts
export default defineNuxtConfig({
... other configuration parameters here
  image: {
    providers: {
      hygraph: {
        baseurl: "https://media.graphassets.com"
      }
    }
  }
})
```
In the above config, we are using Hygraph as our image source.

## Getting data from Hygraph

Now that you have created your Nuxt project, it's time to add some data from Hygraph. Start by cloning our demo Hygraph project:

<Button
  href="https://app.hygraph.com/clone/751a6bdf9431476c8b82c543895e6d16?name=Implementation%20Guides"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Click here to clone the demo project</Button>

After cloning, you will have a simple project that contains one content model called **Page** that contains fields for `Title`, `Slug`, and `Body`; and one content entry.

If you navigate to the Schema builder and click on the **Page** model, you will see this:

![Demo project - Page model](/images/docs/implementations/demo-project-page-model.png)

And if you navigate to the Content editor and view the sample entry details, you'll see this:

![Demo project - Sample content entry](/images/docs/implementations/demo-project-sample-entry.png)

## Content API

Before you can connect Nuxt to Hygraph, you will need to configure **Content API** access permissions for unauthenticated requests.

To do this, we'll to go **Project settings > Access > API Access > Content API** in our Hygraph project, scroll to find the **Manage Content API access permissions** box and click `Initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, we will copy the `High Performance Read-only Content API` endpoint from **Project settings > Access > API Access > Endpoints**. You will use it to connect Nuxt to Hygraph later on.

## Testing a query in the API playground

Next, you should test if you can fetch the information in the sample content entry that we showed you earlier. To do this, navigate to the API Playground in your project and use the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query Page {
  page(where: {slug: "hygraph-works-with-any-framework"}) {
    title
    body {
      text
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "page": {
      "title": "Hygraph works with any framework!",
      "body": {
        "text": "No matter the framework you choose, Hygraph is there for you and all your content needs. "
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

If you execute the query, the response should fetch the sample query in the demo project you cloned.

## Generating Hygraph content with Nuxt

[After enabling API access](/docs/implementations/nuxt/nuxt#content-api), you can start using the **Pages** query with your Nuxt app to render content.

### Adding Tailwind CSS to Nuxt

Use the terminal to go back to your Nuxt app, and type the following command:

```
npm install @nuxtjs/tailwindcss
```

This will install Tailwind CSS, so you have a few base styles to use with your content.

### Installing Nuxt GraphQL Client

The next step is to add the `nuxt-graphql-client` module.

This helps with codegen for GraphQL functionality and types, and provides an easy way to use GraphQL API's in Nuxt.

To install the client, type the following command:

```
npm install nuxt-graphql-client
```

After the installation finishes, add the following to your `nuxt.config.ts` file:

```js
// nuxt.config.ts

export default defineNuxtConfig({
  devtools: { enabled: true },
  modules: ['@nuxtjs/tailwindcss','nuxt-graphql-client']
})
```

The  `nuxt-graphql-client` module offers some convenient helpers for typing and querying.

Add the following to your `.env` file so the module knows how to connect to Hygraph for the introspection of the schema to make types, and to be able to query.

```
GQL_HOST=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```

<Alert theme="warning">
Make sure that `<HYGRAPH_CDN_LOCATION>` and `<ID>` match your endpoint.
</Alert>

Want to see Nuxt and Hygraph in action? Watch a quick video on how to connect `Nuxt` and `Hygraph`:
<VideoEmbed videoId="M8QFTViZSMw"/>
### Adding GraphQL queries

Now that you have all the packages installed, create a queries folder and add your GraphQL queries in there as files with a `.gql` extension:

**Query all pages** - file location & name: `./queries/pages.gql`
```graphql
# File name: pages.gql
# File location ./queries/pages.gql
query Pages {
  pages {
    title
    slug
    body {
      text
    }
  }
}
```
**Query single page by slug** - file location & name: `./queries/page.gql`
```graphql
# File name: page.gql
# File location: ./queries/page.gql
query Page($slug: String!) {
  page(where: { slug: $slug }) {
    title
    body {
      text
    }
  }
}
```

The  `nuxt-graphql-client` module finds this folder and automatically creates types and convenience functions for all queries it finds.

<Alert theme="info" title="Do you want to learn more about nuxt-graphql-client?">
<Link href="https://www.youtube.com/watch?v=Keqn1RT8FwQ" target="_blank">We made a video about how it works!</Link>
</Alert>

### Getting a list of pages for the homepage

After adding your `.env` file, go to your `index.vue` file in the `pages` directory and add the following code:
<Tabs panelHeight={280}>
  <TabsItem label="JavaScript">
```js
// File location: /pages/index.vue
// Homepage: Get a list of pages from the Hygraph
<script setup>
const { pages } = await GqlPages();
</script>
// Render the list of pages with links to each page by slug
<template>
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">Hygraph Implementation Guides demo</h1>
    <p class="mb-4 text-lg">Click the links below to see other pages</p>
    <ul class="mb-8 list-disc list-inside">
      <li v-for="page in pages" :key="page.slug">
        <nuxt-link :to="`/page/${page.slug}`" class="underline">{{
          page.title
        }}</nuxt-link>
      </li>
    </ul>

    <p>
      <a
        class="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700"
        href="https://hygraph.com/docs/implementations"
        target="_blank"
      >
        Implementation Docs
      </a>
    </p>
  </div>
</template>
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// File location: /pages/index.vue
// Homepage: Get a list of pages from the Hygraph
<script setup lang="ts">
const { pages } = await GqlPages();
</script>
// Render the list of pages with links to each page by slug
<template>
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">Hygraph Implementation Guides demo</h1>
    <p class="mb-4 text-lg">Click the links below to see other pages</p>
    <ul class="mb-8 list-disc list-inside">
      <li v-for="page in pages" :key="page.slug"> <!-- Fix the variable name in the :key directive -->
        <nuxt-link :to="`/page/${page.slug}`" class="underline">{{
          page.title
        }}</nuxt-link>
      </li>
    </ul>

    <p>
      <a
        class="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700"
        href="https://hygraph.com/docs/implementations"
        target="_blank"
      >
        Implementation Docs
      </a>
    </p>
  </div>
</template>
```
  </TabsItem>
</Tabs>

![Homepage](/images/docs/implementations/next/next-homepage.png)


### Creating dynamic page routes with Nuxt

Now, that we have a list of pages in our homepage, we need to create a dynamic route for each page. To do this, create a new directory in the `pages` directory called `page` and a file called `[slug].vue` inside this directory.

Add the following code:

<Tabs>
  <TabsItem label="JavaScript">
```js
<!-- File: pages/page/[slug].vue -->
<script setup>
const route = useRoute()

const { data: page } = await useAsyncData('page', () =>
  GqlPage({ slug: route.params.slug }).then(res => res.page)
)
</script>

<template>
  <div class="m-12" v-if="page">
    <h1 class="mb-4 text-5xl font-bold">{{ page.title }}</h1>
    <p class="mb-8 text-lg">{{ page.body.text }}</p>

    <p>
      <NuxtLink to="/" class="underline">Back to homepage</NuxtLink>
    </p>
  </div>
</template>
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// file location & name: pages/page/[slug].vue
// Dynamic page: Get a single page by slug from the Hygraph
<script setup lang="ts">
const route = useRoute();
const { page } = await GqlPage({ slug: route.params.slug });
</script>
// Render the page title and body text
<template>
  <div class="m-12">
    <h1 class="mb-4 text-5xl font-bold">{{ page.title }}</h1>
    <p class="mb-8 text-lg">{{ page.body.text }}</p>

    <p>
      <nuxt-link to="/" class="underline">Back to homepage</nuxt-link>
    </p>
  </div>
</template>
```
</TabsItem>
</Tabs>

### Code overview

The template section of our `Vue` component contains the markup that renders our content on the homepage.

In the script section, we use the `GqlPage()` function to ask Hygraph with our **Page** query to fetch the `title`, `slug`, and `body`.

![Dynamic page](/images/docs/implementations/next/next-dynamic-page.png)

Congratulations! You have a homepage and a dynamic page route to render all pages and their content.

<Alert theme="info" title="Pro Tip">
This was a simple and quick example of how to fetch and render content from Hygraph using Nuxt.

For more complete implementation examples, <Link href="https://app.hygraph.com/" target="_blank">clone a starter</Link>.
</Alert>


---
# Hygraph resources for Nuxt

Source: https://hygraph.com/docs/implementations/nuxt/resources

Here's a list of our resources for Nuxt:

| Resource name                                                                                                        | Resource type                | Description                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://www.youtube.com/watch?v=Keqn1RT8FwQ" target="_blank">How to use Nuxt 3 with Hygraph and GraphQL</Link>                            | Video                        | In this video, our DevRel Tim shows how to use Nuxt 3 with GraphQL to query a Hygraph remote REST API source.                                                                                                                                         |
| <Link href="https://www.youtube.com/watch?v=E9jxm4h4A48" target="_blank">The Hygraph SKNCRE starter with Nuxt and Tailwind</Link>                     | Video                        | SKNCRE is a composable commerce demo with Hygraph, Nuxt, Tailwind, and an external API for product data.                                                                                                                                              |
| <Link href="https://www.youtube.com/watch?v=PhCXH2M7OzM" target="_blank">How to build a live-voting experience with Hygraph, Nuxt and Supabase</Link> | Video - Livestream recording | Our DevRel Tim discusses a conference talk where he created a guitar karaoke experience in which the audience could live-vote what 4-song mashup he'd play. In this live stream we deep dive into how this was built with Supabase, Hygraph and Nuxt. |


---
# Skncre + Nuxt

Source: https://hygraph.com/docs/implementations/nuxt/skncre-nuxt

## Overview

Use our **Skncre** starter with Nuxt to create a composable cosmetics storefront starter.

## Quickstart: Clone the Skncre Nuxt starter

To get up and running quickly with Nuxt and Hygraph, clone our **Skncre** starter:

1. <Link href="https://app.hygraph.com/clone/f67b7c52af504cd9a19de912423b2e40?name=Hygraph%20SKNCRE" target="_blank">Clone the Hygraph project</Link>
2. <Link href="https://github.com/timbenniks/skncre-cosmetics-hygraph" target="_blank">Get the Nuxt code from Github</Link>

Install **Skncre** via terminal:

```
npx degit git@https://github.com/hygraph/skncre-starter-nuxt.git
```

Alternatively, you can <Link href="https://app.hygraph.com/" target="_blank">clone <strong>Skncre</strong> from the Hygraph project directory</Link> from the selection of available starters.

<Alert theme="info" title="Starter recap">

All Hygraph starters are located on the project directory after to login. Scroll past the “My Projects” section to the “Start a new Project” section and choose the E-commerce shop starter.

This will create a new hygraph project as well as the frontend template for a website.

</Alert>

### Connecting Hygraph to Nuxt

Change directory to your new **Skncre** project and install dependencies if needed using `yarn install`.

[After initializing permissions](/docs/implementations#content-api), we'll create a `.env` file by renaming the `.env.example` file in the root of our Nuxt project.

Add the endpoint URL we copied from Hygraph inside the `.env` file, like this:

```
GQL_HOST=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```

### Configure Hygraph assets to work with Nuxt

To work with Nuxt image module, we need to specify Hygraph as an image provider by adding the base URL in the `nuxt.config.ts` file.

Your config file should contain the following code:

```js
// nuxt.config.ts
export default defineNuxtConfig({
... other configuration parameters here
  image: {
    providers: {
      hygraph: {
        baseurl: "https://media.graphassets.com"
      }
    }
  }
})
```

In this case, we are using Hygraph as our image source. You can add additional image providers as needed to the Nuxt config file.

![Skncre](/images/docs/implementations/nuxt/skncre.png)

Once you add the `GQL_HOST` and configure the image source, you can spin up your development server with the command `yarn run dev` and your app will be available at `https://localhost:3000.`

<Alert theme="info" title="Pro Tip">

For more Nuxt implementations, <Link href="https://github.com/hygraph/hygraph-nuxt-microblog-starter" target="_blank">check out our Nuxt microblog starter!</Link>

</Alert>


---
# Hygraph snippets for Nuxt

Source: https://hygraph.com/docs/implementations/nuxt/snippets

Here's a list of our snippets for Nuxt. Each snippet links to you the repo:

| Snippet name                                                                                  | Description                                                         |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nuxtjs" target="_blank">NuxtJs</Link>                 | This example demonstrates how to query from Hygraph with `Nuxt.js`. |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-nuxtjs-graphql" target="_blank">NuxtJs GraphQL</Link> | Hygraph, `NuxtJS` & `nuxt-graphql-client`.                          |


---
# Hygraph starters for Nuxt

Source: https://hygraph.com/docs/implementations/nuxt/starters

Here's a list of our starters for Nuxt. Each starter links to you their Marketplace page:

| Starter name                                                                                                 | Description                                                                            |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/marketplace/starters/skncre-starter" target="_blank">SKNCRE, a Hygraph cosmetics brand e-commerce demo</Link> | A composable commerce demo with Hygraph, NuxtJS, and an external API for product data. |
| <Link href="https://hygraph.com/marketplace/starters/nuxt-microblog" target="_blank">Nuxt Microblog</Link>                                    | A microblog using Nuxt.js, Tailwind CSS, and Hygraph.                                  |


---
# Remix + Hygraph

Source: https://hygraph.com/docs/implementations/remix/remix

## Overview

<Link href="https://remix.run/" target="_blank">Remix</Link> is a modern web framework that focuses on developer experience and performance by leveraging a React-based approach to build web applications and UIs. It emphasizes server-side rendering, efficient data loading, and seamless integration with various backends and cloud environments to create fast, scalable, and interactive web experiences.


## Creating a new Remix app

To initialize a new `Remix` project using Javascript, use the JS template flag.

Open up your terminal, navigate to where you want your project, and run the following command:

```
npx create-remix@latest --template remix-run/remix/templates/remix-javascript
```
Remix app using TypeScript:
```
npx create-remix@latest
```
### Add Tailwind CSS to your Remix app

1. To add Tailwind CSS to your Remix app, run the following command:

    ```
    npx install tailwindcss postcss autoprefixer -D && npx tailwindcss init
    ```
2. Update the `tailwind.config.js` file to reflect the following:

    ```js
    /** @type {import('tailwindcss').Config} */
    export default {
      content: ["./app/**/*.{js,jsx,ts,tsx}"],
      theme: {
        extend: {}
      },
      plugins: []
    };
    ```
3. Create a `postcss.config.cjs` file in the root of your project with the following code:

    ```js
    module.exports = {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    },
    };
    ```
4. Update the `app/tailwind.css` file (or create it if it doesn't exist), to import Tailwind's styles:

    ```css
    @tailwind base;
    @tailwind components;
    @tailwind utilities;
    ```
5. Finally, make sure to import the `app/tailwind.css` file in your `app/root.jsx` file:
    ```js
    import "./tailwind.css";
    ```

Now, you should be able to use Tailwind CSS classes in your Remix app.

<Alert theme="warning">
We will use Remix with Tailwind CSS added in the [Getting data from Hygraph](/docs/implementations/remix/remix#getting-data-from-hygraph) section of this guide.
</Alert>

## Getting data from Hygraph

Now that you have created your Remix app, it's time to add some data from Hygraph. Start by cloning our demo Hygraph project:

<Button
  href="https://app.hygraph.com/clone/751a6bdf9431476c8b82c543895e6d16?name=Implementation%20Guides"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Click here to clone the demo project</Button>

After cloning, you will have a simple project that contains one content model called **Page** that contains fields for `Title`, `Slug`, and `Body`; and one content entry.

If you navigate to the Schema builder and click on the **Page** model, you will see this:

![Demo project - Page model](/images/docs/implementations/demo-project-page-model.png)

And if you navigate to the Content editor and view the sample entry details, you'll see this:

![Demo project - Sample content entry](/images/docs/implementations/demo-project-sample-entry.png)

## Content API

Before you can connect Remix to Hygraph, you will need to configure **Content API** access permissions for unauthenticated requests.

To do this, go **Project settings > Access > API Access > Content API** in your Hygraph project, scroll to find the **Content Permissions** box that reads **Would you like us to initialize some defaults?**, and click `Yes, initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, copy the `High Performance Content API` endpoint from **Project settings > Access > API Access > Endpoints**. You use it to connect Remix to Hygraph later on.

## Testing a query in the API playground

Next, you should test if you can fetch the information in the sample content entry that we showed you earlier. To do this, navigate to the API Playground in your project and use the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query Page {
  page(where: {slug: "hygraph-works-with-any-framework"}) {
    title
    body {
      text
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "page": {
      "title": "Hygraph works with any framework!",
      "body": {
        "text": "No matter the framework you choose, Hygraph is there for you and all your content needs. "
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

If you execute the query, the response should fetch the sample query in the demo project you cloned.

## Connecting Remix to Hygraph

In `Remix`, save your `VITE_HYGRAPH_URL` in an `.env` file on the project root.

As a result, you will be able to call this key with `process.env.VITE_HYGRAPH_URL` in any of your files.

This will be where we paste [the endpoint URL we copied from Hygraph](#content-api):

```
VITE_HYGRAPH_URL=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```
Your root directory will include the following files:
```
remix/
┣ app/
┣ node_modules/
┣ public/
┣ .env
┣ .eslintrc.cjs
┣ .gitignore
┣ README.md
┣ package-lock.json
┣ package.json
┣ postcss.config.cjs
┣ tailwind.config.js
┗ vite.config.js
```

Want to see Remix and Hygraph in action? Watch a quick video on how to connect `Remix` and `Hygraph`:
{/* <VideoEmbed videoId="AAHu9X5WAjY"/> REPLACE WITH CORRECT VIDEO EMBED*/}

## Generating Hygraph content with Remix

[After enabling API access](#content-api), you can start using the **Pages** query with your Remix app to render content.

### Installing a GraphQL Client

GraphQL clients make communication easier by abstracting away small details and implementing additional features such as static typing of our query results.

We will use the npm package `graphql-request` because it is lightweight, has excellent TypeScript support, and supports both `Node.js` and browsers.

Use the terminal to go back to your Remix app, and type the following command:

```
npm i -D graphql-request graphql
```
This will install a GraphQL client.
### Getting a list of pages for the homepage

After installing the GraphQL client, go to the `app/routes` directory and modify or create a file called `_index.jsx` or `_index.jsx` if you are using TypeScript, and add the following code:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// File location: /app/routes/_index.jsx
// Homepage: Get a list of pages from the Hygraph
import { json } from "@remix-run/node";
import { useLoaderData, Link } from "@remix-run/react";
import { GraphQLClient, gql } from "graphql-request";

export const meta = () => {
  return [
    { title: "Hygraph Implementation Demo" },
    { name: "description", content: "Welcome to Hygraph, a headless CMS" },
  ];
};

const getPagesQuery = gql`
  {
    pages {
      slug
      title
    }
  }
`;

export let loader = async () => {
  const hygraph = new GraphQLClient(
    process.env.VITE_HYGRAPH_URL,
  );

  const { pages } = await hygraph.request(getPagesQuery);
  //console.log(pages)
  return json({ pages });
};

export default function Index() {
  let data = useLoaderData();
  return (
    <div className="m-12">
      <h1 className="mb-4 text-5xl font-bold">
        Hygraph Implementation Guides demo
      </h1>
      <p className="mb-4 text-lg">Click the links below to see other pages</p>
      <ul className="mb-8 list-disc list-inside">
      {data.pages.map(({ slug, title }) => (
        <li key={slug}>
          <Link to={`/page/${slug}`} prefetch="intent" className="underline">
            <a>{title}</a>
          </Link>
        </li>
      ))}
    </ul>
    <p>
        <button
          className="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700">
          <Link
            to ="https://hygraph.com/docs/implementations"
            target="_blank">Implementation Docs</Link>
        </button>
      </p>
    </div>
  );
}
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// File location: /app/routes/_index.tsx
// Homepage: Get a list of pages from the Hygraph
import { json } from "@remix-run/node";
import { useLoaderData, Link } from "@remix-run/react";
import { GraphQLClient, gql } from "graphql-request";

export const meta = () => {
  return [
    { title: "Hygraph Implementation Demo" },
    { name: "description", content: "Welcome to Hygraph, a headless CMS" },
  ];
};
interface Pages {
  slug: string;
  title: string;
}
const getPagesQuery = gql`
  {
    pages {
      slug
      title
    }
  }
`;
export let loader = async () => {
  const hygraph = new GraphQLClient(
    process.env.VITE_HYGRAPH_URL as string,
    {
      headers: {},
    }
  );

  const { pages }: { pages: Pages[] } = await hygraph.request(getPagesQuery);
  //console.log(pages)
  return json({ pages });
};
export default function Index() {
  let data = useLoaderData();

  return (
    <div className="m-12">
      <h1 className="mb-4 text-5xl font-bold">
        Hygraph Implementation Guides demo
      </h1>
      <p className="mb-4 text-lg">Click the links below to see other pages</p>
        <ul className="mb-8 list-disc list-inside">
        {(data as { pages: Pages[] }).pages.map(({ slug, title }) => (
          <li key={slug}>
            <Link to={`/page/${slug}`} prefetch="intent" className="underline">
              <a>{title}</a>
            </Link>
          </li>
        ))}
      </ul>
    <p>
        <button
          className="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700">
          <Link
            to ="https://hygraph.com/docs/implementations"
            target="_blank">Implementation Docs</Link>
        </button>
      </p>
    </div>
  );
}
```
  </TabsItem>
</Tabs>

**Code overview for the homepage**

The code you just added creates a query function that fetches a list of pages from Hygraph and renders them on the homepage as a bulleted list of links.

When you run your Remix app by using the command `npm run dev`, you should get a list of pages on the homepage.

![Homepage](/images/docs/implementations/next/next-homepage.png)

### Creating dynamic page routes with Remix

Now, that we have a list of pages in our homepage, we need to create a dynamic route for each page. To do this, create a new file in the `app/routes` directory called `page.$slug.jsx` or `page.$slug.tsx`. When finished, your source directory should resemble the following structure:

```
// Remix app directory structure
app/
┣ routes/
┃ ┣ _index.tsx
┃ ┗ page.$slug.tsx
┣ entry.client.tsx
┣ entry.server.tsx
┣ root.tsx
┗ tailwind.css
```

Add the following code to your `page.$slug.jsx` or `page.$slug.tsx` file:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// file location & name: src/routes/page/[...slug]/+page.js
// Dynamic page: Get a single page by slug from the Hygraph
import { json } from "@remix-run/node";
import { useLoaderData, Link } from "@remix-run/react";
import { GraphQLClient, gql } from "graphql-request";

export const meta = () => {
  return [
    { title: "Hygraph Implementation Demo" },
    { name: "description", content: "Welcome to Hygraph, a headless CMS" },
  ];
};

const getPageBySlug = gql`
  query Page($slug: String!) {
    page(where: { slug: $slug }) {
      title
      slug
      body {
        text
      }
    }
  }
`;
export let loader = async ({ params }) => {
  const { slug } = params;

  const hygraph = new GraphQLClient(
    process.env.VITE_HYGRAPH_URL,
  );

  const { page } = await hygraph.request(getPageBySlug, {
    slug
  });

  return json({ page });
};

export default function Page() {
  let data = useLoaderData();

  return (
    <div className="m-12">
      <h1 className="mb-4 text-5xl font-bold">{data.page.title}</h1>
      <p className="mb-8 text-lg">{data.page.body.text}</p>
      <p>
        <Link to="/" className="underline">
          Back to homepage
        </Link>
      </p>
    </div>
  );
}
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// file location & name: src/routes/page/[...slug]/+page.ts
// Dynamic page: Get a single page by slug from the Hygraph
import { json } from "@remix-run/node";
import { useLoaderData, Link } from "@remix-run/react";
import { GraphQLClient, gql } from "graphql-request";

export const meta = () => {
  return [
    { title: "Hygraph Implementation Demo" },
    { name: "description", content: "Welcome to Hygraph, a headless CMS" },
  ];
};

interface Page {
  title: string;
  slug: string;
  body: {
    text: string;
  };
}

const getPageBySlug = gql`
  query Page($slug: String!) {
    page(where: { slug: $slug }) {
      title
      slug
      body {
        text
      }
    }
  }
`;
export let loader = async ({ params }: { params: { slug: string } }) => {
  const { slug } = params;
  const hygraph = new GraphQLClient(
    process.env.VITE_HYGRAPH_URL as string,
    {
      headers: {},
    }
  );
  const { page } = await hygraph.request(getPageBySlug, {
    slug
  }) as { page: Page }; // Type assertion

  return json({ page });
};
export default function Page() {
  let data = useLoaderData() as { page: Page };
  return (
    <div className="m-12">
      <h1 className="mb-4 text-5xl font-bold">{data.page.title}</h1>
      <p className="mb-8 text-lg">{data.page.body.text}</p>
      <p>
        <Link to="/" className="underline">
          Back to homepage
        </Link>
      </p>
    </div>
  );
}
```
  </TabsItem>
</Tabs>

**Code overview for dynamic page route**

The code you just added will create a dynamic route for each page. It will fetch the page content from Hygraph and render it on the page.

When you run your Remix app by using the command `npm run dev`, you should be able to see the page content when you click on a page link.

![Dynamic page](/images/docs/implementations/next/next-dynamic-page.png)

Congratulations! You have a homepage and a dynamic page route to render all pages and their content.

<Alert theme="info" title="Pro Tip">
This was a simple and quick example of how to fetch and render content from Hygraph using Remix.

For more complete implementation examples, <Link href="https://app.hygraph.com/" target="_blank">clone a starter</Link>.
</Alert>


---
# Hygraph resources for Remix

Source: https://hygraph.com/docs/implementations/remix/resources

Here's a list of our resources for Remix:

| Resource name                                                                                                                              | Resource type                | Description                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/blog/preview-mode-with-remix" target="_blank">How to Create a Preview Mode with Remix and Hygraph</Link>                                    | Blog post                    | Learn how to create and initialize a Preview Mode for your content using Remix and Hygraph.                                                                                                 |
| <Link href="https://hygraph.com/blog/build-a-stock-market-website" target="_blank">Working with Remote Sources to build a stock market website using Remix</Link>           | Blog post                    | Learn how to use a finance API as a Remote Source with Hygraph and how to display the content using Remix, Tremor, and Tailwind CSS.                                                        |
| <Link href="https://hygraph.com/blog/integrate-hydrogen-with-hygraph" target="_blank">Integrating a headless CMS with Shopify Hydrogen</Link>                               | Blog post                    | Learn how to integrate Shopify Hydrogen with Hygraph. |



---
# Hygraph snippets for Remix

Source: https://hygraph.com/docs/implementations/remix/snippets

Here's a list of our snippets for Remix. Each snippet links to you the repo:

| Snippet name                                                                | Description                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/hygraph-implementation-guides/tree/main/remix" target="_blank">Remix</Link> | Example snippet that shows how to use Remix(JS and TS) with Hygraph. |


---
# Hygraph starters for Remix

Source: https://hygraph.com/docs/implementations/remix/starters

Here's a list of our starters for Remix. Each starter links to you their Marketplace page:

| Starter name                                                                | Description                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------ |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-remix-documentation" target="_blank">Documentation</Link> | A documentation app built built using React, Remix, and TailwindCSS with Hygraph.  |


---
# Hygraph resources for SvelteKit

Source: https://hygraph.com/docs/implementations/sveltekit/resources

Here's a list of our resources for SvelteKit:

| Resource name                                                                                                                              | Resource type                | Description                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Link href="https://hygraph.com/blog/sveltekit-starter-blog-with-hygraph" target="_blank">SvelteKit Starter Blog with Hygraph</Link>                                        | Blog post                    | Learn how to use SvelteKit with Hygraph using a blog starter.                                                                                                                               |
| <Link href="https://hygraph.com/blog/implement-federated-content-in-hygraph-and-svelte" target="_blank">How to implement federated content in Hygraph and Svelte</Link>     | Blog post                    | Learn how to federate content in Hygraph and SvelteKit using GraphQL. |
| <Link href="https://hygraph.com/blog/svelte-typescript" target="_blank">How to Use TypeScript with Svelte</Link>                                                            | Blog post                    | Learn how to work with TypeScript in a SvelteKit project. |
| <Link href="https://hygraph.com/blog/how-to-get-started-with-sveltekit-and-graphql" target="_blank">How to get started with SvelteKit and GraphQL</Link>                    | Blog post                    | Learn how to load a set of posts as static HTML created during the site build and then implement a load more button in React to query Hygraph for more content and load that onto the page. |
| <Link href="https://github.com/ObieMunoz/graph-image" target="_blank">Advanced Lazy-Loading and Compression with Svelte/SvelteKit and Hygraph</Link>                        | Community tool               | Community developed: Lazy load imaging tool for Hygraph and SvelteKit.  |
| <Link href="https://www.youtube.com/watch?v=zH2qG9YwN3s" target="_blank">SvelteKit Crash Course w/ Tailwind CSS and DaisyUI, GraphQL and dynamic routes</Link>              | Video                        | Learn SvelteKit and how to use it with Hygraph. |



---
# Hygraph snippets for SvelteKit

Source: https://hygraph.com/docs/implementations/sveltekit/snippets

Here's a list of our snippets for SvelteKit. Each snippet links to you the repo:

| Snippet name                                                                | Description                                                   |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-sveltekit" target="_blank">SvelteKit</Link> | Example snippet that shows how to use the SvelteKit with Hygraph. |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-sveltekit-and-graphql-request" target="_blank">SvelteKit and GraphQL Request</Link> | Example snippet that shows how to use the SvelteKit and GraphQL Request with Hygraph. |
| <Link href="https://github.com/hygraph/hygraph-examples/tree/master/with-sveltekit-and-urql" target="_blank">SvelteKit and URQL</Link> | Example snippet that shows how to use the SvelteKit and URQL with Hygraph. |


---
# Hygraph starters for SvelteKit

Source: https://hygraph.com/docs/implementations/sveltekit/starters

Here's a list of our starters for SvelteKit. Each starter links to you their Marketplace page:

| Starter name                                                                | Description                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------ |
| <Link href="https://hygraph.com/marketplace/starters/hygraph-sveltekit-portfolio" target="_blank">Developer Portfolio</Link> | A developer portfolio to showcase experience and work using SvelteKit, Daisy UI, and Hygraph. |


---
# Sveltekit + Hygraph

Source: https://hygraph.com/docs/implementations/sveltekit/sveltekit

## Overview

<Link href="https://kit.svelte.dev/" target="_blank">SvelteKit</Link> is web app framework for building highly optimized web applications. It is a framework that is built on top of Svelte, a compiler that turns your components into highly efficient JavaScript code.


## Creating a new SvelteKit app

To start, we need to initialize a new `SvelteKit` project. Open up your terminal, navigate to where you want your project, and run the following command:

```
npm create svelte@latest my-app
```
### Add Tailwind CSS to your SvelteKit app

1. To add Tailwind CSS to your SvelteKit app, run the following command:

```
npx svelte-add@latest tailwindcss
```
2. Update the `tailwind.config.js` file to reflect the following:

		```js
		/** @type {import('tailwindcss').Config} */
		export default {
			content: ['./src/**/*.{html,js,svelte,ts}'],

			theme: {
				extend: {}
			},

			plugins: []
		};
		```
3. Create a `postcss.config.cjs` file in the root of your project with the following code:

		```js
		module.exports = {
		plugins: {
			tailwindcss: {},
			autoprefixer: {},
		},
		};
		```
4. Update the `src/app.css` file (or create it if it doesn't exist), to import Tailwind's styles:

		```css
		@tailwind base;
		@tailwind components;
		@tailwind utilities;
		```
5. Finally, make sure to import the `src/app.css` file in your `src/+layout.svelte` file:
		```jsx
		<!-- src/+layout.svelte -->
		<script>
		import '../app.css';
		</script>
		<main>
			<slot>
			</slot>
		</main>
		```
Now, you should be able to use Tailwind CSS classes in your Svelte components.

<Alert theme="warning">
We will use SvelteKit with Tailwind CSS added in the [Getting data from Hygraph](/docs/implementations/sveltekit/sveltekit#getting-data-from-hygraph) section of this guide.
</Alert>

## Getting data from Hygraph

Now that you have created your SvelteKit app, it's time to add some data from Hygraph. Start by cloning our demo Hygraph project:

<Button
  href="https://app.hygraph.com/clone/751a6bdf9431476c8b82c543895e6d16?name=Implementation%20Guides"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
>Click here to clone the demo project</Button>

After cloning, you will have a simple project that contains one content model called **Page** that contains fields for `Title`, `Slug`, and `Body`; and one content entry.

If you navigate to the Schema builder and click on the **Page** model, you will see this:

![Demo project - Page model](/images/docs/implementations/demo-project-page-model.png)

And if you navigate to the Content editor and view the sample entry details, you'll see this:

![Demo project - Sample content entry](/images/docs/implementations/demo-project-sample-entry.png)

## Content API

Before you can connect SvelteKit to Hygraph, you will need to configure **Content API** access permissions for unauthenticated requests.

To do this, go **Project settings > Access > API Access > Content API** in your Hygraph project, scroll to find the **Content Permissions** box that reads **Would you like us to initialize some defaults?**, and click `Yes, initialize defaults`:

![Content API permissions](/images/docs/implementations/public-content-api-permissions.png)

Finally, copy the `High Performance Content API` endpoint from **Project settings > Access > API Access > Endpoints**. You use it to connect SvelteKit to Hygraph later on.

## Testing a query in the API playground

Next, you should test if you can fetch the information in the sample content entry that we showed you earlier. To do this, navigate to the API Playground in your project and use the following query:

<Tabs panelHeight={220}>
  <TabsItem label="Query">

```graphql
query Page {
  page(where: {slug: "hygraph-works-with-any-framework"}) {
    title
    body {
      text
    }
  }
}
```

  </TabsItem>
  <TabsItem label="Response">

```json
{
  "data": {
    "page": {
      "title": "Hygraph works with any framework!",
      "body": {
        "text": "No matter the framework you choose, Hygraph is there for you and all your content needs. "
      }
    }
  }
}
```

  </TabsItem>
</Tabs>

If you execute the query, the response should fetch the sample query in the demo project you cloned.

## Connecting SvelteKit to Hygraph

In `SvelteKit`, save your `VITE_HYGRAPH_URL` in an `.env` file on the project root.

As a result, you will be able to call this key with `import.meta.env.VITE_HYGRAPH_URL` in any of your files.

This will be where we paste [the endpoint URL we copied from Hygraph](#content-api):

```
VITE_HYGRAPH_URL=https://<HYGRAPH_CDN_LOCATION>.cdn.hygraph.com/content/<ID>/master
```
Your root directory will include the following files:
```
sveltekit/
┣ .svelte-kit/
┣ node_modules/
┣ src/
┣ static/
┣ .env
┣ .eslintignore
┣ .eslintrc.cjs
┣ .gitignore
┣ .npmrc
┣ .prettierignore
┣ .prettierrc
┣ README.md
┣ package-lock.json
┣ package.json
┣ postcss.config.js
┣ svelte.config.js
┣ tailwind.config.js
┗ vite.config.js
```
Want to see SvelteKit and Hygraph in action? Watch a quick video on how to connect `SvelteKit` and `Hygraph`:
{/* <VideoEmbed videoId="AAHu9X5WAjY"/> REPLACE WITH CORRECT VIDEO EMBED*/}

## Generating Hygraph content with SvelteKit

[After enabling API access](#content-api), you can start using the **Pages** query with your SvelteKit app to render content.

### Installing a GraphQL Client

GraphQL clients make communication easier by abstracting away small details and implementing additional features such as static typing of our query results.

We will use the npm package `graphql-request` because it is lightweight, has excellent TypeScript support, and supports both `Node.js` and browsers.

Use the terminal to go back to your SvelteKit app, and type the following command:

```
npm i -D graphql-request graphql
```

This will install a GraphQL client.

### Getting a list of pages for the homepage

After installing the GraphQL client, go to the `src/routes` directory and create file called `+page.js` or `+page.ts` if you are using TypeScript, and add the following code:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// File location: /src/routes/+page.js
// Homepage: Get a list of pages from the Hygraph
import { GraphQLClient } from 'graphql-request';

/** @type {import('./$types').PageLoad} */
export const load = async () => {
	const hygraph = new GraphQLClient(
        import.meta.env.VITE_HYGRAPH_URL,
		{
			headers: {}
		}
	);

	const { pages } = await hygraph.request(
		`{
            pages {
                slug
                title
            }
        }`
	);

	return {
		pages
	};
};
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// File location: /src/routes/+page.ts
// Homepage: Get a list of pages from the Hygraph
import { GraphQLClient } from 'graphql-request';

/** @type {import('./$types').PageLoad} */
export const load = async () => {
	const hygraph = new GraphQLClient(import.meta.env.VITE_HYGRAPH_URL, {
		headers: {}
	});

	interface Page {
		slug: string;
		title: string;
	}

	interface PagesResponse {
		pages: Page[];
	}

	const { pages } = await hygraph.request<PagesResponse>(
		`{
            pages {
                slug
                title
            }
        }`
	);

	return {
		pages
	};
};
```
  </TabsItem>
</Tabs>

Now that you have a query function that returns the list of pages from Hygraph, you can render them on the homepage. To do this, go to the `src/routes` directory and create or modify a file called `+page.svelte` and add the following code:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// File location: /src/routes/+page.svelte
// Homepage: Render a list of pages from the Hygraph on the homepage
<script>
	/** @type {import('./$types').PageData} */
	export let data;
	const pages = data.pages;
</script>

<main>
	<div class="m-12">
		<h1 class="mb-4 text-5xl font-bold">Hygraph Implementation Guides demo</h1>
		<p class="mb-4 text-lg">Click the links below to see other pages</p>
		<ul class="mb-8 list-disc list-inside">
			{#each pages as page (page.slug)}
				<li>
					<a href={`/${page.slug}`} class="underline">{page.title}</a>
				</li>
			{/each}
		</ul>
		<p>
			<a
			  class="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700"
			  href="https://hygraph.com/docs/implementations"
			  target="_blank"
			>
			  Implementation Docs
			</a>
		</p>
	</div>
</main>
```
</TabsItem>
<TabsItem label="TypeScript">
```ts
// File location: /src/routes/+page.svelte
// Homepage: Render a list of pages from the Hygraph on the homepage
<script lang="ts">
	/** @type {import('./$types').PageData} */
	export let data;
	const pages = data.pages;
</script>
<main>
	<div class="m-12">
		<h1 class="mb-4 text-5xl font-bold">Hygraph Implementation Guides demo</h1>
		<p class="mb-4 text-lg">Click the links below to see other pages</p>
		<ul class="mb-8 list-disc list-inside">
			{#each pages as page (page.slug)}
				<li>
					<a href={`/page/${page.slug}`} class="underline">{page.title}</a>
				</li>
			{/each}
		</ul>
		<p>
			<a
				class="px-4 py-2 my-6 font-bold text-white bg-indigo-500 rounded hover:bg-indigo-700"
				href="https://hygraph.com/docs/implementations"
				target="_blank"
			>
				Implementation Docs
			</a>
		</p>
	</div>
</main>
```
</TabsItem>
</Tabs>

![Homepage](/images/docs/implementations/next/next-homepage.png)


### Creating dynamic page routes with SvelteKit

Now, that we have a list of pages in our homepage, we need to create a dynamic route for each page.

To do this, create a new directory in the `src/routes` directory called `page/[...slug]`, a file called `+page.js` or `+page.ts` inside this directory. The default SvelteKit install creates a Svelte file called `+page.svelte`, we will use this file to render the page content.

After this, your source directory should look like this:

```
src/
┣ lib/
┃ ┗ index.js
┣ routes/
┃ ┣ page/
┃ ┃ ┗ [...slug]/
┃ ┃   ┣ +page.js
┃ ┃   ┗ +page.svelte
┃ ┣ +layout.svelte
┃ ┣ +page.js
┃ ┗ +page.svelte
┣ app.css
┗ app.html
```

Add the following code to your `+page.js` or `+page.ts` file:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// file location & name: src/routes/page/[...slug]/+page.js
// Dynamic page: Get a single page by slug from the Hygraph
import { GraphQLClient } from 'graphql-request';

/** @type {import('./$types').PageLoad} */
export const load = async ({ params }) => {
	const hygraph = new GraphQLClient(import.meta.env.VITE_HYGRAPH_URL, {
		headers: {}
	});

	const { page } = await hygraph.request(
		`query Page($slug: String!) {
            page(where: { slug: $slug }) {
	            title
                slug
                body    {
                text
                    }
	            }
	        }`,
		{
			slug: params.slug
		}
	);

	return {
		page
	};
};
```
  </TabsItem>
  <TabsItem label="TypeScript">
```ts
// file location & name: src/routes/page/[...slug]/+page.ts
// Dynamic page: Get a single page by slug from the Hygraph
import { GraphQLClient } from 'graphql-request';

/** @type {import('./$types').PageLoad} */
export const load = async ({ params }) => {
	const hygraph = new GraphQLClient(import.meta.env.VITE_HYGRAPH_URL, {
		headers: {}
	});

	interface Page {
		slug: string;
		title: string;
		body: {
			text: string;
		};
	}

	interface PageResponse {
		page: Page;
	}

	const { page } = await hygraph.request<PageResponse>(
		`query Page($slug: String!) {
            page(where: { slug: $slug }) {
	            title
                slug
                body {
                	text
                	}
	            }
	        }`,
		{
			slug: params.slug
		}
	);

	return {
		page
	};
};
```
  </TabsItem>
</Tabs>

Now that you have a query function that returns the page content from Hygraph and created a dynamic route for individual pages, we can render page content using a Svelte file.

To do this, go to the `src/routes/page/[...slug]` directory and modify the file `+page.svelte` with the following code:

<Tabs panelHeight={400}>
  <TabsItem label="JavaScript">
```js
// File location: /src/routes/page/[...slug]/+page.svelte
// Homepage: Render page content from the Hygraph in a dynamic route
<script>
	/** @type {import('./$types').PageData} */
	export let data;
	const page = data.page;
</script>

<main>
    <div class="m-12">
      <h1 class="mb-4 text-5xl font-bold">{page.title}</h1>
      <p class="mb-8 text-lg">{page.body.text}</p>

      <p>
        <a href="/" class="underline">Back to homepage</a>
      </p>
    </div>
</main>
```
</TabsItem>
<TabsItem label="TypeScript">
```ts
// File location: /src/routes/page/[...slug]/+page.svelte
// Homepage: Render a list of pages from the Hygraph on the homepage
<script>
	/** @type {import('./$types').PageData} */
	export let data;
	const page = data.page;
</script>
<main>
    <div class="m-12">
      <h1 class="mb-4 text-5xl font-bold">{page.title}</h1>
      <p class="mb-8 text-lg">{page.body.text}</p>

      <p>
        <a href="/" class="underline">Back to homepage</a>
      </p>
    </div>
</main>
```
</TabsItem>
</Tabs>

### Code overview

The code you just added will create a dynamic route for each page. It will fetch the page content from Hygraph and render it on the page.


![Dynamic page](/images/docs/implementations/next/next-dynamic-page.png)

Congratulations! You have a homepage and a dynamic page route to render all pages and their content.

<Alert theme="info" title="Pro Tip">
This was a simple and quick example of how to fetch and render content from Hygraph using SvelteKit.

For more complete implementation examples, <Link href="https://app.hygraph.com/" target="_blank">clone a starter</Link>.
</Alert>


---
# Smartling app changelog

Source: https://hygraph.com/docs/integrations/changelog-smartling

## August 2026

**Improvements**

- **Sort entries by when they were last updated**: The Smartling view now sorts entries by most recently updated by default, so content that changed since your last translation round appears first. A **SORT BY** control lets you switch to least recently updated, or back to the previous ID ordering.

## July 2026

**Improvements**

- **Filtering by title on models with a fixed set of title values**: When a model's title field is an enum, the Smartling view now shows a **TITLE** dropdown listing that enum's values, so those models can be filtered by title instead of offering a free-text search that might never match.
- **Warning for long-running syncs**: Selecting a large number of locales for a single sync can push the import close to timing out. The sync dialog now shows a warning when an import has been running unusually long, suggesting you split the work into smaller batches.
- **Clearer message when the Content API token has expired**: An expired or unauthorized Content API token previously surfaced as a generic unknown error while loading entries or running Smartling actions. The app now states that the Content API token has expired or failed authentication, so you can update it and retry.
- **Content API errors are shown instead of hidden**: When the Content API rejects a request while loading entries, the app now shows what the Content API actually reported rather than a generic error.

**Fixes**

- **Sync failing silently for entries with many locales and rich text list fields**: Syncing an entry that combined several rich text list items with many locales could generate a single oversized request that the platform rejected outright, silently dropping the whole conversion step. Large conversions are now split into smaller requests, so syncs of this size complete successfully.
- **`Search by Title` failing with an unknown error**: On models whose title field is not a single-line text field, or that have no title field at all, searching by title returned no results and showed an `UNKNOWN_ERROR` message even though matching entries were visible. Title search is now offered only in the form each model supports, such as free text, a value dropdown, or not at all. Where it is not possible, the search box is disabled and the app points you to Search by ID instead; locale and locale status filters continue to work as usual.
- **Multi-value text translations lost during import**: When syncing completed translations back from Smartling, fields holding a list of text values (for example, option lists or tag lists) could come back untranslated, with the translated values dropped without any warning. These list translations are now imported correctly.
- **Failed syncs reported as successful**: When Hygraph rejected an entry update or a localized asset upload during import, for example because of a schema or locale mismatch, the entry was still counted as successfully synced and marked as translated. Such entries now appear in the failed-entries alert instead, so you can see and retry what actually failed.

## June 2026

**Fixes**

- **Copying entry IDs when clipboard access is blocked**: Copying an entry ID could fail silently in embedded app contexts where browser permissions block direct clipboard writes. The app now falls back to a compatible copy method, and shows an error if copying still cannot complete.
- **Localized asset uploads for draft-only entries**: Importing completed translations could update localized asset text but leave the images themselves pending, because the app looked for asset upload information outside the draft stage or reused localization state across assets in the same gallery. Asset uploads now use draft entry data and evaluate each asset separately, so translated images are re-uploaded during sync.

## April 2026

**Fixes**

- **Draft entries could not be submitted for translation**: Submitting entries that existed only as drafts could fail before upload because the app prepared an empty Smartling batch. Draft entries can now be submitted reliably, and empty batches are no longer sent.
- **Setup screen stuck on `Saving`**: On the app setup screen, saving could stay in a loading state indefinitely even after the configuration had been applied successfully, so there was no confirmation and a reload was needed to verify the changes. Saving now completes and confirms reliably.
- **Missing assets after import for list-based content blocks**: Translated entries using list fields that contained only referenced assets could come back with those lists empty, even though the original entry had assets selected. The export and import flow now preserves direct asset references in list fields, so translated entries keep their media.

## March 2026

**Fixes**

- **Translations rejected for list fields containing rich text**: When syncing translations back from Smartling, list fields whose items contain rich text sub-properties were sent to Hygraph with Smartling metadata still attached. Hygraph rejected the payload and the update failed without a visible error. Translation import now unwraps this nested metadata before updating the entry.

## February 2026

**Improvements**

- **Security** - Next.js dependency updated to address CVE-2025-66478.

**Fixes**

- **Asset uploads skipped in certain component translations**: While translating content that contained image assets inside components with no translatable text, the asset file upload was skipped. This left localized assets stuck in the `ASSET_CREATE_PENDING` state and prevented publishing. All referenced assets are now uploaded during sync, even when the surrounding component has no translatable fields.

- **String array translations missing or incorrect**: Localized string arrays could be split into multiple Smartling segments or returned in an unexpected structure, causing translations to appear incorrectly or not at all in Hygraph. String arrays are now sent as single translation units and properly unwrapped when updating content.

- **Smartling tab error for models with acronyms in API IDs**: Selecting models with acronyms in their API IDs (for example, `FAQItem`) could trigger a `Failed to fetch entries` error and a GraphQL error `field 'FAQItem' is not defined` due to incorrect field name generation. Acronym casing is now preserved so entries load correctly.

## January 2026

**Fixes**

- **Empty Smartling jobs when title field API ID was missing**: Submitting entries for translation could create Smartling jobs without content if the model did not include a configured title field API ID. The app now handles this case correctly so content is always included in the translation job.

- **Translations not appearing in Hygraph after successful sync**: In some cases, sync completed successfully but translations were not visible in the editor. This occurred because Smartling job files were missing `id` and `__typename` fields for component union items. These fields are now included so translations can be applied correctly.

- **Missing localized assets after re-importing Smartling jobs**: Re-importing localized jobs could result in image assets appearing greyed out or missing in non-default locales. Assets nested inside deeply structured components were not always uploaded. Nested asset references are now correctly detected and uploaded so localized images appear in all locales.

- **Incorrect entry selection when switching models**: Changing the selected model did not reset entry selection, which could cause the selection count or chosen entries to be incorrect. Entry selection now resets when the model changes and is tracked using entry IDs instead of indices.

- **Import failures caused by empty asset list items**: Empty asset translations within list or component array fields could cause import errors. These empty entries are now skipped so imports complete reliably.

## November 2025

**Improvements**

- **Clear section and field context in Smartling exports**: With smarter key and instruction generation, Smartling exports now include clearer section and field context, making translations easier to understand.
- **Preserved localized assets**: When reuploading assets, existing localized files are retained instead of being overwritten.

**Fixes**

- **Complete export coverage**: Entries now export with all nested components and Rich Text content included.
- **Accurate filter counts**: Adjusting Smartling search filters no longer leaves behind an incorrect or stale selection count.
- **Reliable asset array handling**: Empty asset arrays within component arrays no longer cause Smartling import errors.

## October 2025

**Improvements**

- **Asset translation support**: You can translate assets directly.
- **Smartling job updates**: When updated strings are pushed to an existing Smartling job, they show the `Awaiting authorization` status.
- **Rich text translation**: Rich text fields in both basic and modular components are translated.

## September 2025

**Improvements**

- **Stale translation detection**: Outdated entries are clearly highlighted, with filters to view **All**, **Only Outdated**, or **Only Up to Date** translations.
- **Enhanced navigation**: Edit links for entries open in a new tab for a smooth workflow.
- **Support for modular components**: Fixed issues that previously caused crashes during import or export.
- **Better error handling**: Clearer messages help you troubleshoot issues faster.

## November 2024

**Fixes**

- **Boolean exports** - Boolean fields are no longer included in exports. Previously, exported boolean fields (`true`/`false`) were translated to strings, which resulted in import failures.


---
# Connect your Hygraph project to Adminix

Source: https://hygraph.com/docs/integrations/connect-adminix

Adminix is a cloud workflow automation platform that companies can use to create processes using serverless technology.

## What you can do with the Hygraph-Adminix integration

- Create custom automation workflows directly on the Hygraph user interface, such as sending an email every time a new product is sold.

## Prerequisites to use this integration

- You must have a Hygraph account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have an Adminix account. If you don't have one, you can request one <Link href="https://www.adminix.io/" target="_blank">here</Link>.
  - You must have created a workspace in Adminix.
  - You will also need a workspace **access token** & **project ID**. You will find this information in your Adminix account. Step 4 of the [integration flow](/docs/integrations/connect-adminix#how-to-install-the-adminix-app) explains exactly where each of them is located.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## How to install the Adminix app

To install apps on Hygraph, you should go to our <Link href="https://hygraph.com/marketplace" target="_blank">marketplace</Link>, and find the **Adminix app**. Click on it to open the page, then click on the **Install Adminix for Hygraph** button to start the installation flow. Follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8qbjaql07w5crzd6baq" caption="Adminix installation" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to your Hygraph project homepage.
2. Click on the `Install Adminix` button.
3. Click on `Yes` if you have an Adminix account. The following screen will display as a result:

   ![Adminix settings](/images/docs/integrations/adminix/adminix-settings.png)

4. You need to complete the following settings to connect Adminix to Hygraph. This information can be found within your Adminix account.
   - **Provider ID:** to get your provider ID, log into your Adminix account, navigate to **Manage Workspaces**, and select the workspace you want to use. Then, go to the **Providers** option on the left sidebar, choose a provider to edit, and copy the provider ID from the URL.
   - **Access Token:** to get your access token, log into your Adminix account, navigate to **Edit Profile**, then scroll down to the **Personal Access Tokens** section. You may have to create one by clicking on the `Generate new Token` button.
   - **Region:** dropdown menu that allows you to select Europe or USA.
5. Once you have completed all the fields, click on the `Save` button, located at the top right of the screen.

### No Adminix account?

If you do not have an Adminix account and therefore you clicked `No` on step 3 of the [integration flow](/docs/integrations/connect-adminix#how-to-install-the-adminix-app), you will be given the possibility to fill out a form so that the Adminix team can contact you and help you set up.

![Adminix contact form](/images/docs/integrations/adminix/adminix-contactform.png)

## How to create Adminix workflows in Hygraph

![Create a workflow](/images/docs/integrations/adminix/adminix-create-workflow.png)

Once you have successfully concluded the integration, you can start creating workflows. To do so, follow these steps:

1. Navigate to the **Workflows** tab located to the left of the screen.
2. Click on the `+New` button at the top right corner of the screen.
3. Complete all the required information. You will be able to add a `Name` and a `Description` of your choice, and then you will use dropdown menus to select a `Content Model`, a `Stage` and `Actions`.

   ![Create workflow screen](/images/docs/integrations/adminix/adminix-create-workflow-screen.png)

4. Click on the `Save` button. You will be redirected to the initial workflows view. The workflow will have been created empty, so you then need to [edit](/docs/integrations/connect-adminix#how-to-edit-a-workflow) it to add information.

## How to edit a workflow

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8ochu3r07vxr1pfn2oi" caption="Edit a workflow" />

1. Navigate to the **Workflows** tab located to the left of the screen.
2. Click on the pencil icon of the workflow you want to edit. This will display the workflow editor, which has two tabs:
   - **Design:** this is where you create your workflow.
   - **Executions:** this screen shows processes execution information, such as **ID**, **start** and **end** timestamps, **status** - which can be _Succeeded_ or _Failed_ - and an action button that, when clicked, will display the execution's data output.

## Resources

- Click <Link href="https://www.adminix.io/" target="_blank">here</Link> to access the Adminix website.


---
# Connect your Hygraph project to Akeneo

Source: https://hygraph.com/docs/integrations/connect-akeneo

**Akeneo** is a composable SaaS-based solution that allows organizations to improve Product Experience through product information management and product data intelligence.

## What you can do with the Hygraph-Akeneo integration

With this app you can orchestrate, activate, and optimize product experiences across all owned and unowned channels, including eCommerce, mobile, print, social, points of sale, and beyond.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have an **Akeneo** account. If you don't have one yet, you can start a free trial <Link href="https://www.akeneo.com/start-free-trial/" target="_blank">here</Link> or request a demo <Link href="https://www.akeneo.com/demo/" target="_blank">here</Link>.
- You must have your <Link href="https://www.akeneo.com/what-is-a-pim/" target="_blank">Akeneo PIM</Link> ready. Your PIM is the URL of your Akeneo account. You can copy it from the browser directly; it should look similar to this `https://<YOUR-PROJECT-NAME>.cloud.akeneo.com/`.
- You must create connection settings for your Hygraph project. To do this, go to **Connect > Connection settings** in your Akeneo dashboard, and click `Create`. You'll need to provide a `Label` and a `Code` to identify the app, then use the `Flow type` dropdown to select `Data source`.
  - This takes you to your Akeneo credentials: the `Client ID`, `Secret`, `Username`, and `Password`. Akeneo will show you your `Secret` and `Password` credentials only once, so make sure you save them somewhere.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Akeneo app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-akeneo-app" target="_blank">here</Link> to install the Akeneo App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/Jg1MszpiR9m9zrsm7qUn" caption="Install Akeneo app" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click `Install app`.
2. The permissions pop-up will display. Clicking `Authorize app` finishes the installation and takes you to the app configuration screen.
3. Next, you need to configure the app. To do that, you first need to fill in your `PIM` and the `Client ID`, `Client Secret`, `Username`, and `Password`. We explained how to get this information [in the prerequisites section](/docs/integrations/connect-akeneo#prerequisites-to-use-this-integration).

   <Alert theme="info" title="Pro Tip">

   - You can find these credentials by going to **Connect > Connection settings** in your Akeneo Dashboard and clicking on the connection you created as part of the [prerequisites for this integration](/docs/integrations/connect-akeneo#prerequisites-to-use-this-integration).
   - Akeneo calls `Secret` the same key that Hygraph calls `Client Secret`.
   - Akeneo will show you your `Secret` and `Password` credentials only once, so make sure you save them somewhere.

   </Alert>

4. Click `Save config settings` to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

## Add the Akeneo field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/39bDNvzhTMOCx4FQyhau" caption="Add Akeneo field to model" />

1. Navigate to the **Schema** builder.
2. Select the model that you want to add the **Akeneo** field to.
3. Select the **Akeneo** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your Akeneo field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the `Field options` section.
6. Click `Add`.

## Use Akeneo in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/qtuZZ68eRkiOOpX3YwvV" caption="Use Akeneo in Hygraph" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Akeneo** for.
3. Click `+ Add entry` to create a new entry or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Akeneo** section of the screen and click on `Add Akeneo asset`. This opens a new screen where you can select and export assets into your Hygraph content entry. This screen contains a number of input and dropdown filters; [click here to learn how to use the Akeneo filters in the Hygraph UI](/docs/integrations/connect-akeneo#how-to-use-akeneo-filters).
5. Select the asset(s) you want, and then click `Export`. If you configured your Akeneo field to allow multiple assets, you will be able to select several assets here. As you select assets, the rows will turn a darker shade of gray to indicate that you selected them.
6. After selecting the asset(s) you want and returning to the content entry, your selection will display on the list.
   ![Akeneo - Images in content entry](/images/docs/integrations/akeneo/images-content-entry.png)
   You can optionally use the six dots icon to drag and drop the assets on the list to organize them in the order you want.
7. Finally, click `Save` or `Save & Publish`, as needed.

## How to use Akeneo filters

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8sehu3z07vxi25tmi7t" caption="How to use Akeneo filters" />

Akeneo filters have two types of inputs:
- **Standard inputs:**  To use them, you need to enter complete search strings - partial strings are not supported by the Akeneo API.
- **Dropdown selects:** When you select the dropdown, the app begins fetching all categories and families from the catalog structure. You can then select specific categories or families to refine results displayed on the table.

You can select conditions for both standard and dropdown filters.

<Alert theme="info">

<Link href="https://help.akeneo.com/serenity-build-your-catalog/30-serenity-manage-your-families-and-variant-families?from_search=131344156" target="_blank">Learn more about Akeneo asset families and variant families here</Link>

</Alert>

## Resources

- <Link href="https://help.akeneo.com/serenity-connect-your-pim/serenity-manage-your-connections#grab-your-credentials" target="_blank">Akeneo documentation on managing your connections</Link>
- <Link href="https://www.akeneo.com/wp-content/uploads/2021/11/Akeneo_eBook_PIM_101_EN.pdf" target="_blank">Akeneo's Product Information Management 101</Link>

&nbsp;


---
# Connect your Hygraph project to Aprimo

Source: https://hygraph.com/docs/integrations/connect-aprimo

**Aprimo** is an AI-powered content operations platform that allows you to organize, store, retrieve, and distribute digital assets in a centralized and structured manner.

## What you can do with the Hygraph-Aprimo integration

With this app you can manage, measure, and monitor your digital assets right within your Hygraph UI.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have an **Aprimo** account. If you don't have one yet, you can book a demo <Link href="https://go.aprimo.com/get-a-demo-of-aprimo" target="_blank">here</Link>.
- You must get the following information from <Link href="https://developers.aprimo.com/digital-asset-management/rest-api/authorization/" target="_blank">your Aprimo account</Link> and have it at hand for installation: `Tenant name`, `Client ID`, `Client secret`.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Aprimo app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-aprimo-app" target="_blank">here</Link> to install the Aprimo app on **Hygraph**, then follow these steps:

<VideoEmbed videoId="6V1FK5U4Jsc" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click on `Install app`.
2. The permissions pop-up will display. Click on `Authorize app` to continue. You will be redirected to the configuration screen.
3. Fill in the `Tenant name`, `Client ID`, `Client secret` fields with the information your copied from your <Link href="https://go.aprimo.com/get-a-demo-of-aprimo" target="_blank">Aprimo account</Link>. 
4. Click on `Save config settings` to finalize the installation process. A pop-up notification on the bottom right corner of the screen will indicate that the changes have been saved.

## Add the Aprimo field to your model

<VideoEmbed videoId="3-JyDEZ5_Oc" />

1. Navigate to the **Schema** builder.
2. Select the model that you want to add the **Aprimo** field to and click on it.
3. Select the **Aprimo** field from the **Add fields** right sidebar.
4. Complete the `Display name` field; this will autocomplete the `API ID` field. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your Aprimo field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the `Field options` section.
6. Click `Add` to save.

## Use Aprimo in your Hygraph project

<VideoEmbed videoId="34clsLc-fTE" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Aprimo** field for.
3. Click on the `+ Add entry` button or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Aprimo** section of the screen and click on `Add Aprimo asset`. If you haven't logged into Aprimo, you may need to enter your login credentials to continue. This opens a new screen where you can select one or more of you existing assets, depending on field configuration.
5. Select the asset you want by clicking on it. If your Aprimo field is configured for multiple assets, you can use the checkboxes to select the assets you want. Click `Select` on the top-right corner of the screen to add the selected assets to the content entry.

    <Alert theme="info" title="Pro Tip">

    - If your Aprimo field is configured to select only one asset, Aprimo will let you select which rendition of the image you want to add to your entry. [Check out this section of the guide to learn how to do this](/docs/integrations/connect-aprimo#aprimo-image-renditions)
    - If you cannot view your images in the picker screen, check out our [troubleshooting section](/docs/integrations/connect-aprimo#i-cant-view-my-images).

    </Alert>

6. After selecting the asset(s) you want and returning to the content entry, your selection will display on the list. You can optionally use the six-dots handlebar to drag and drop the assets to organize them in the order you want.
7. Finally, click `Save` or `Save & Publish` - depending on your workflow - to save your entry.

## Aprimo image renditions

If you Aprimo field is configured to allow only one value, clicking on `Add Aprimo asset` will still display the selection screen, but there will be a diference in how the process follows.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8u8jaqt07w5i45cmiy8" caption="Aprimo image renditions" />

Instead of using checkboxes to select the image you want, you will click on an image, and you will be taken to a second selection screen where you can select from a variety of image renditions.

<Alert theme="info">

Different image renditions will only be available if the images were configured to have multiple versions in Aprimo.

</Alert>

Select a rendition and then click `Select` to add the image to your content entry.

## Troubleshooting

### I can't view my images

If you cannot view your images in the picker screen, make sure that the images in your Aprimo account have public links.

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8w6jar107w5o7jcf8p3" caption="Aprimo public links" />

To create a public link:

1. Go to **Drafts** in your Aprimo account
2. Select the image you want to give public links to
3. Scroll down to the  **Public links** section of the screen and click `Create public link...`
4. Use the checkboxes to select the renditions you want to make available and click `Create`

## Resources

- <Link href="https://developers.aprimo.com/docs/rest-api/dam/dam-intro" target="_blank">Aprimo documentation for digital assets</Link>

&nbsp;


---
# Connect your Hygraph project to AWS S3

Source: https://hygraph.com/docs/integrations/connect-aws-s3

**AWS S3** is a service that provides object storage through a web service interface.

## What you can do with the Hygraph-AWS S3 integration

With this app you can access assets stored in your AWS S3 bucket directly from the Hygraph UI and then use them in your Hygraph project.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have an **AWS** account. If you don't have one yet, you can create one <Link href="https://portal.aws.amazon.com/billing/signup#/start/email" target="_blank">here</Link>.
- You must have your `Access key` and `Secret access key` ready. [Here](/docs/integrations/connect-aws-s3#user-setup) you can see how to get them.
- You must have access to AWS bucket. We explain how to do this [here](/docs/integrations/connect-aws-s3#access-to-aws-bucket).

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the AWS S3 app

Click <Link href="https://app.hygraph.com/apps/aws_s3/new" target="_blank">here</Link> to install the AWS S3 App on **Hygraph**, then follow these steps:

<VideoEmbed videoId="GeIx4r0XxGU" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click `Install app`.
2. The permissions pop-up will display. Clicking `Authorize app` finishes the installation and takes you to the app configuration screen.
3. Next, you need to configure the app. To do that, you first need to fill in your credentials. We explained how to get this information [in the prerequisites section](/docs/integrations/connect-aws-s3#prerequisites-to-use-this-integration).
4. Click `Save config settings` to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

## Add the AWS S3 field to a model

<VideoEmbed videoId="y3mABvNQJKE" />

1. Navigate to the **Schema** builder.
2. Select the model that you want to add the **S3** field to.
3. Select the **S3** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your Akeneo field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the `Field options` section.
6. Click `Add`.

## Use AWS S3 in the Content editor

<VideoEmbed videoId="jUFZw2ubxdk" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **S3** field for.
3. Click `+ Add entry` to create a new entry or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **S3** section of the screen and click on `Add S3 asset`. This opens a new screen where you can select and export assets into your Hygraph content entry. This screen shows the root folder selection as default view.

  <Alert theme="info" title="Pro Tip">
  - The selected root is the top level allowed, you cannot go back from that.
  - The overall root of the bucket is identified with a `/` alone. You can navigate the folders from the root on.
  </Alert>

5. Select the asset(s) you want, and then click `Export`. If you configured your S3 field to allow multiple assets, you will be able to use the checkboxes to select several assets here.
6. After selecting the asset(s) you want and returning to the content entry, your selection will display on the list. You can optionally use the six dots icon to drag and drop the assets on the list to organize them in the order you want.
7. Finally, click `Save` or `Save & Publish`, as needed.

## Access to AWS bucket

### User setup

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9gshu5h07vx8mg5snv4" caption="AWS Bucket - User setup" />

1. Go to **Amazon IAM > Users** and click `Create user` to create a new one.
2. Attach a policy clicking `Add permissions` in your user details view. You can either add the user to a group or attach policies directly.

    <Alert theme="info" title="Minimal list of permissions needed:">

    - `GetObject`
    - `ListBuckets`
    - `ListObjectsV2`
    - `PutObject`

    </Alert>

3. Go to **Security credentials** and click `Create access key` to create a new access key. You can only have two at a time, so if you have two already the button will be grayed out.
4. Under **Access key best practices & alternatives**, select `Third-party service`.
5. Copy your `Access key` and `Secret access key` and store them somewhere safe.

### Bucket setup

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9eehu5907vxa57fn2gk" caption="AWS Bucket - Bucket setup" />

1. Go to **Amazon S3 > Buckets** and click `Create bucket` to create a new one.
2. In your bucket's detail view, go to **Permissions** and disable `Block all public access`.
3. Add a bucket policy.

**Parts of the policy:**

```json
{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::aorltestbucket/*"
}
```

Public read access allows using assets that you store in this bucket on your public website after being selected in Hygraph:

```json
{
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::688394999555:user/ao-test-user"
            },
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::aorltestbucket/*"
        }
```

In the example above, `Principal` is the user you have created earlier, and `Resource` is the name of your bucket.

This policy allows the user that we'll be using to connect the Hygraph app to manage assets.

## Resources

- <Link href="https://docs.aws.amazon.com/s3/" target="_blank">AWS S3 documentation</Link>



---
# Connect your Hygraph project to BigCommerce

Source: https://hygraph.com/docs/integrations/connect-bigcommerce

**BigCommerce** is a SaaS provider for merchants running online businesses. The company's platform includes online store creation, search engine optimization, hosting, and marketing and security for small to enterprise sized businesses.

## What you can do with the Hygraph-BigCommerce integration

With this app you can continue to use **BigCommerce** as your preferred headless commerce solution for products and eCommerce assets. By installing the BigCommerce app, you can bring your BigCommerce products into **Hygraph** projects with the rest of your content.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project).
- You must have a **BigCommerce** account. If you don't have one yet, you can <Link href="https://www.bigcommerce.com/" target="_blank">visit their website</Link> and contact their team.
- You must have your BigCommerce `Storefront ID` and `API token`:

      - **Storefront ID:** You can easily find this value in the URL of your BigCommerce dashboard between `store-` and `.mybigcommerce.com/manage/dashboard`.

        <Alert theme="info">

        For example:

        `https://store-YOUR_STOREFRONT_ID.mybigcommerce.com/manage/dashboard`

        </Alert>

  - **API Token:** The **API Token** is the **Access Token** in your BigCommerce dashboard. You can find it by going to **Settings > API > Store-level API accounts > Create API account**. Make sure you enable full permissions and save.

        After you save, a window will pop up displaying the BigCommerce API credentials, and a `.txt` file containing your `Access token` will automatically download.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the BigCommerce app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-bigcommerce-app" target="_blank">here</Link> to install the **BigCommerce** App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x92dhu4f07vx4j6nzpev" caption="BigCommerce installation" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to the **Configure BigCommerce** section of your Hygraph project.
2. Fill in the `Storefront ID` and the `API Token`. Click [here](/docs/integrations/connect-bigcommerce#prerequisites-to-use-this-integration) to learn how to find this information in your BigCommerce dashboard.
3. Click on the `Save` button. A pop-up notification in the lower right corner of the screen will indicate that the changes have been saved.

## Add the BigCommerce product field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x8y7hu4707vx8tjjw6no" caption="Add the BigCommerce Product field to your model" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **BigCommerce Product** field to.
3. Select the **BigCommerce Product** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`. This screen allows you to control different properties of your **BigCommerce Product** field: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
5. Click on the `Create` button.

## Use BigCommerce in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x90ajar907w59kloggxj" caption="Use BigCommerce in your Hygraph project" />

1. Navigate to the **Content** editor.
2. Select the default that you configured the **BigCommerce Product** field for.
3. Click on the `+ Create entry` button or, alternatively, edit an existing entry.
4. Locate the **BigCommerce product** section of the screen and click on `Select product from BigCommerce`. As a result, a new screen will display, showing the products available in your **BigCommerce** store.
5. Use the checkboxes next to the pictures to select the product you wish to add to the entry, then click on the `Add selected product` button.
6. Now that the product has been added to the entry, you can click on `Save` or `Save & Publish`, as needed.

## Resources

- Click <Link href="https://developer.bigcommerce.com/" target="_blank">here</Link> to access BigCommerce's documentation.
- Click <Link href="https://developer.bigcommerce.com/api-reference/a315bf0c38635-storefront-token" target="_blank">here</Link> for more information on BigCommerce GraphQL Tokens.


---
# Connect your Hygraph project to Bynder

Source: https://hygraph.com/docs/integrations/connect-bynder

**Bynder** is digital asset management platform that helps you conquer the chaos of growing content, touchpoints, and relationships.

## What you can do with the Hygraph-Bynder integration

With this app you can continue to use Bynder as your preferred DAM solution for images, videos, and other digital assets. By installing the Bynder app, you can bring your Bynder assets into Hygraph projects with the rest of your content.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **Bynder** account. If you don't have one yet, you can <Link href="https://www.bynder.com/en/" target="_blank">contact the team</Link> about it.
- You must have a **Bynder domain**. <Link href="https://support.bynder.com/hc/en-us/articles/360013875240-How-To-Create-A-Portal-Custom-URL" target="_blank">Here</Link> is some information on how to get one.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Bynder app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-bynder-app" target="_blank">here</Link> to install the **Bynder** App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/2ltPkSKbSbS46u6NCfM9" caption="Install Bynder app" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to the **Configure Bynder** section of your Hygraph project.
2. Fill in the `Bynder domain` and use the checkboxes to select the allowed asset types.
3. Click on the `Save` button. A pop-up notification in the lower right corner of the screen will indicate that the changes have been saved.

<Alert theme="info">

Allowed asset types are selected in the initial configuration, but can be edited later by navigating to <b>Apps > Bynder card edit button</b>, in your Hygraph project.

</Alert>

## Add the Bynder asset picker to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/EDSqmi9OTnKErumZZtKr" caption="Add Bynder asset picker field" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **Bynder** asset picker field to, and click on it.
3. Select the **Bynder** asset picker field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`. This screen allows you to control different properties of your **Bynder** asset picker field: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
5. Click on the `Create` button.

## Use Bynder in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/7T8ZkDysSmGqmZSJafqB" caption="Use Bynder in your Hygraph project" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Bynder asset** picker field for.
3. Click on the `+ Add entry` button or, alternatively, edit an existing entry.
4. Locate the **Bynder asset** section of the screen and click on `Select asset from Bynder`. As a result, a new screen will display, showing the assets available in your Bynder domain. Only the asset types selected during the [configuration process](/docs/integrations/connect-bynder#install-the-bynder-app) will display here.
5. Select the asset you wish to add to the entry, then click on the `Add asset` button.
6. Now that the asset has been added to the entry, you can click on `Save` or `Save & Publish`, as needed.

## Resources

- <Link href="https://support.bynder.com/hc/en-us" target="_blank">Bynder documentation</Link>


---
# Use ChatGPT to generate product descriptions in Hygraph

Source: https://hygraph.com/docs/integrations/connect-chatgpt

This document is a step-by-step guide on how to streamline product description creation for a sample ecommerce system.

You'll learn how to expand Hygraph's management features to create a custom field that can generate text using ChatGPT's completion capability.

## What you can do with this integration

If you have an online shop, you might want to consider using AI to generate your product descriptions. With the <Link href="https://hygraph.com" target="_blank">Hygraph</Link> headless CMS, you can easily create and fill custom fields with <Link href="https://platform.openai.com/docs/api-reference" target="_blank">ChatGPT</Link>-generated text, saving you significant time and creative energy.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/quickstart#create-a-project).
- You must be familiar with <Link href="https://nextjs.org/" target="_blank">Next.js</Link>.
- You must be familiar with <Link href="https://react.dev/" target="_blank">React.js</Link>.
- You must have <Link href="https://nodejs.org/en" target="_blank">node 14.6.0 or newer</Link> installed.
- You must have <Link href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/" target="_blank">npm 9.5.0</Link> installed.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Setting up Hygraph for AI-generated product descriptions

You can access the code for this project <Link href="https://github.com/rajsanka/auto-fill-description" target="_blank">on GitHub</Link>.

### Set up your Hygraph project

Log into your Hygraph account and create a new project using the **Commerce Shop** starter. Give it a name - this tutorial uses **My Clothing Shop** - and add a description.

Keep the `Include Template Content` checkbox selected, use the dropdown to select a region to host the project, and click `Add Project`.

Once your project is built, navigate to **Project settings > Access > Endpoints**, and make note of the content endpoint; you'll use it to retrieve data.

### Create a simple React Application to view data

Clone Hygraph's <Link href="https://github.com/hygraph/hygraph-examples.git" target="_blank">GitHub project</Link> and change the directory to `hygraph-examples/with-reactjs`.

Use a text editor to modify `src/App.js`.

Change the request URL to the content endpoint you noted earlier from Hygraph's project settings.

Change the Product GraphQL to retrieve the `name`, `ID`, and `slug` along with the description and images.

Your code should look as follows:

```
	{
        products {
          id
          name
          slug
          description
          images {
            url
            width
            height
          }
        }
      }
```

Change `src/Product.js` to show the extra fields retrieved:

```
return (
      <div>
          <h1>{product.name}</h1>
          <p>{product.slug}</p>
          <p>{product.description}</p>
          <img src={product.images[0].url} width={product.images[0].width} height={product.images[0].height}/>
      </div>
  );
```

Run `npm install`, then run `npm start`.

You can view the application at `http://localhost:3000/products/snapback`. You can click on a product listing to see more details.

![Commerce Site](/images/docs/integrations/chatgpt/product-details.png)

### Create a custom field element

As mentioned earlier, this tutorial uses a custom field element to generate a product description. While field elements can have various extension types — `String`, `Integer`, `Float`, `JSON`, or complex types that combine several fields into one component — this tutorial uses a `String` field element, shown as a text box with a **Generate Description** button.

We'll use <Link href="https://github.com/hygraph/hygraph-app-nextjs-quick-start.git" target="_blank">Hygraph's boilerplate project</Link> to develop a simple custom field that will allow the user to store and get a String.

Run the following command to generate a Next.js project containing a starter field element and sidebar element:

```
npx create-next-app --example https://github.com/hygraph/hygraph-app-nextjs-quick-start auto-fill-description
```

This is what the created directory structure looks like:

![Directory structure of project](/images/docs/integrations/chatgpt/directory-structure.png)

<Alert title="Pro Tip" theme="info">

- The `pages/setup.tsx` file includes the code that runs when this app is installed for a project.
- The basic field element code is located in `pages/field.tsx`.
- The sidebar element code is located in `pages/sidebar.tsx`.
- A standard `pages/api/hello.ts` file implements an API.

</Alert>

**Hygraph offers three node modules for use in the app framework code:**

- `@graphcms/app-sdk`: This contains SDK components like `AppProps`, `FieldExtensionProps`, and `FormSidebarExtensionProps` that give access to often-requested properties for the app, such installation status or access to the form data.
- `@graphcms/app-sdk-react`: This module exposes the SDK components as <Link href="https://blog.logrocket.com/react-render-props-vs-custom-hooks/" target="_blank">custom React hooks</Link>.
- `@hygraph/baukasten`: The node modules under `@hygraph` have to do with UI and rendering. They include layouts, rendering components like `Input` and `TextArea`, icons, and themes, among others.

We'll use the boilerplate setup code for this tutorial, but you can change it to suit your needs. For instance, you could change it so that the OpenAI secret key is configured rather than hardcoded.

Here's the boilerplate code in `field.tsx`:

```
<Flex>
      <Input
          placeholder="Type something here"
          value={value || ""}
          onChange={(e: any) => onChange(e.target.value)}
      />
</Flex>
```

`Flex` is a layout and `Input` is a rendering component provided by Hygraph in the `@hygraph/baukasten` package. The rendering components shown in the following screenshot are also provided by Hygraph:

![hygraph/baukasten package](/images/docs/integrations/chatgpt/baukasten-package.png)

The `FieldExtensionProps` offered by `@graphcms/app-sdk` allows you to access the form data and events like `onChange` and `onBlur`. When the data in the input field is changed, the boilerplate code calls the API's `onChange` method, which stores the modified data in the form.

<Alert theme="info">

Check our [Field element API Reference](/docs/app-framework/api-reference/api-reference-field-element) for more information.

</Alert>

Here's the boilerplate code in `sidebar.tsx`:

```
<Flex>
    <Button flex="1" onClick={() => alert("Hello!")}>
        Click Me
    </Button>
</Flex>
```

As you can see, the boilerplate only provides a button that displays an alert after clicking. For now, let's just run the server with the boilerplate as is and configure the app.

Run `npm install`, then `npm run dev` in the autofill description directory to launch the server on port 3000 by default.

<Alert theme="warning">

When you access the URL directly in the web browser (eg. `http://localhost:3000/setup`), you'll encounter the `SDK connection error, check logs` error. You must use Hygraph for access.

</Alert>

To create the app, select the ecommerce project you created from your <Link href="https://app.hygraph.com/" target="_blank">Hygraph dashboard</Link>. Select `Apps` from the sidebar, then click `Add new app`.

Note that after your app is created, you can't alter the permissions. For this tutorial, select read/write access for all options.

In the `General` tab, add the field element providing the following details:

- **Name:** Auto Fill Description
- **Description:** A String field element to generate descriptions using ChatGPT
- **Avatar URL:** `https://ui-avatars.com/api/?name=String`
- **API ID:** aidescription

![General Details](/images/docs/integrations/chatgpt/app-general-details.png)

In the `Elements` tab, add the field element providing the following details:

- **Element 1**
  - **Name:** Generate Description
  - **API ID:** appCustomField
  - **Type:** `field`
  - **Features:** `FieldRenderer`
  - **Field type:** String
  - **URL:** `https://localhost.3000/field`
  - **Description:** A custom field to generate a description for products

![Add element](/images/docs/integrations/chatgpt/add-element.png)

Click `Register app` and save the `client ID` and `secret` from the pop-up dialogue box.

Close the dialogue and select `Back to app list`. The app you just registered should be listed here.

![Registered app](/images/docs/integrations/chatgpt/registered-app.png)

Your Auto Fill Description app is now created in Hygraph and is currently available for installation on many projects.

Let's go ahead and install it in your `My Clothing Shop` project.

### Install the app in your project

Click on the install icon next to the app. A dialogue displays where you need to select the project you created previously (**My Clothing Shop**), then select **Master Environment**. Finally, click on `Install app`.

![App install](/images/docs/integrations/chatgpt/app-install.png)

A dialogue will appear, where you need to provide the app with the permissions you selected when you created it.

The setup page from the boilerplate code displays after authorization, with the Install component code first. Click `Install App`, then the Configure component code will appear.

![Setup page](/images/docs/integrations/chatgpt/setup-page.png)

Click `Save` to install the app on your project.

The custom field element included in the boilerplate code is now available for use in this project.

### Add the field to the product schema

Navigate to the Schema builder, then select the **Product** model. You will find the custom field on the `Add fields` right sidebar, listed as `Generate Description` under `STRING`. Click on it to add it to the Product model.

![Add description field](/images/docs/integrations/chatgpt/add-description-field.png)

As soon as the field is successfully added to the **Product model**, it will be available in the **Content editor**.

### Display the `Generate Description` button

In order to replace the default input box with a `Generate Description` button over a text area, modify `pages/field.tsx` as follows:

```
    //add this function to FieldElement
    function changevalue() {
    }

    //change the return statement
    return (
        <Stack>
            <Button onClick={ () => changevalue() }>Generate Description</Button>
            <TextArea
                placeholder="Type something here"
                value={value || ""}
                onChange={(e: any) => onChange(e.target.value)}
            />
        </Stack>
    );
```

This switches the component from `Input` to `TextArea`, alters the layout from `Flex` to `Stack`, and adds a button labeled `Generate Description`.

Currently, when you click the button, it simply calls an empty `changevalue` function. You need to add code to generate the description.

### Add an API to call ChatGPT

You want a click on **Generate Description** to build a prompt based on information from the other product fields. ChatGPT's <Link href="https://platform.openai.com/docs/models/gpt-3-5" target="_blank"><code>gpt-3.5-turbo</code> model</Link> will then call <Link href="https://developers.openai.com/api/docs/guides/completions" target="_blank">OpenAI's Completions API</Link> to generate a description. The additional product field values will pass to this API using Next.js's <Link href="https://nextjs.org/docs/api-routes/dynamic-api-routes" target="_blank">dynamic routing feature</Link>.

A hypothetical URL to call the API might be `http://localhost:3000/api/gpt/backpack/back-pack/`, which includes the product `name` and `slug`. This tutorial will design the API to accept product `name`, `slug`, `description`, `price`, and `variants`.

First, register and create an <Link href="https://platform.openai.com/signup" target="_blank">OpenAI API key</Link>. Copy the generated key to use later.

![OpenAI API Key](/images/docs/integrations/chatgpt/open-api-key.png)

Create a directory called `gpt` under `pages/api`, then create a file called `[...product].ts` under this directory. You can refer to OpenAI's <Link href="https://platform.openai.com/docs/api-reference/chat/create?lang=node.js" target="_blank">chat completion API</Link> for the code to call OpenAI.

Use `npm install openai --save` to install the OpenAI node module. Edit your `[...product].ts` file and add this function to call OpenAI for a given prompt and return the completion as a String:

```
const openaifetcher=async (prompt: String) : Promise<String> => {
    const { Configuration, OpenAIApi } = require("openai");

    const configuration = new Configuration({
      apiKey: '<Your openai api key>',
    });
    const openai = new OpenAIApi(configuration);

    const completion = await openai.createChatCompletion({
      model: "gpt-3.5-turbo",
      messages: [{role: "user", content: prompt }],
    });

    return completion.data.choices[0].message.content;
}
```

Make sure to include the handler, which will respond to API calls.

**This code creates a prompt with the following text:**

> A marketing description for a black/medium t-shirt costing $20. Start with this description: A comfortable T-shirt.

The prompt will change depending on the available data. You can play around with different prompts — remember that <Link href="https://github.com/rajsanka/auto-fill-description" target="_blank">GitHub has the whole source code</Link>.

```
type Completion = {
  description: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Completion>
) {
    const { query } = req;
    const { product : [name, slug, description, price, variants] } = query;

    let prompt = `"A marketing description for "`;

    if (variants) {
        prompt += `" a ${variants} "`;
    }

    prompt += `" ${name} "`;

    if (price) {
        prompt += `" costing ${price}"`;
    }

    if (description) {
        prompt += `". Start with this description: ${description}."`;
    }

    openaifetcher(prompt).then((description) => {
        res.status(200).json(`${description}`);
    });
}
```

Access the URL `http://localhost:3000/api/gpt/backpack/back-pack/` in a browser to test the API. Make sure you receive content.

<Alert theme="warning">

Keep in mind that the API created here is not secure. You can add security to ensure that only authorized users access it.

</Alert>

![Generated content](/images/docs/integrations/chatgpt/generated-content.png)

### Call the API on button click

Edit `pages/fields.tsx` to invoke the API you just developed with the appropriate parameters.

The form variable is available in `FieldExtensionProps`, which you can use to access the other values in the form. Declare the form variable in the custom hook together with `value` and `onChange` (`const value, form, onChange = useFieldExtension();`). The async function `getState()` returns all of the values in the form.

Use these values to access additional fields in the `Product` object and build the API URL.

Change the code as follows:

```
function changevalue() {
    const formvalues = form.getState().then((values) => {
        console.log(values.values);
        let api = "/api/gpt/" + values.values.localization_en.name + "/" + values.values.localization_en.slug;
        api += "/" + values.values.localization_en.description;
        api += "/" + values.values.localization_en.price;

        fetch(api).then((res) => {
            const data = res.json();
            data.then((content) => {
                console.log(content);
                onChange(content);
            });
        });
    });
}
```

The values are stored based on localization. In this instance, you've used `localization_en` values. You can change the function to accommodate other requirements, like using unsaved values and other locale data. Following that, the code calls `fetch` to invoke the API and retrieve a description. The `onChange` method sets this as the content of the text area in the custom field element.

Now refresh the Product's content creation screen and click `Generate Description`. ChatGPT should generate a description and populate it into the text box.

![Generated description](/images/docs/integrations/chatgpt/generate-description.png)

Click on `Save` and then publish the product to save and publish the AI description.

You can now change the ecommerce React.js app you created earlier to show `aiProductDescription` instead of `description`—modify the GraphQL in `App.js` to use `aiProductDescription` instead of `description`, and modify `Product.js` to use `product.aiProductDescription` instead of `product.description`.

Load your app page, and it should show the description generated.

<Alert theme="warning" title="Pro Tip">
  Keep in mind that this tutorial uses your local machine to test the custom
  field element. This has to be productionalized (ie. installed, configured,
  secured) and then deployed onto a production server. After that, you can
  change the app details as necessary to service all users.
</Alert>


---
# Connect your Hygraph project to Cloudinary

Source: https://hygraph.com/docs/integrations/connect-cloudinary

Cloudinary empowers companies to deliver visual experiences that inspire and connect by unleashing the full potential of their media.

<Alert theme="warning">

The Cloudinary UIX has been deprecated. If you are using it, you need to replace it with the App. <a href="#migration">Here</a> is a step-by-step guide on how to do it.

</Alert>

## What you can do with the Hygraph-Cloudinary integration

- You can continue to use Cloudinary as your preferred DAM solution for images, videos, and other digital assets, in a similar way that you would [use assets](/docs/api-reference/assets/assets-overview) hosted by Hygraph.

## Prerequisites to use this integration

- You must have a Hygraph account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have an Cloudinary account. If you don't have one, you can create one <Link href="https://cloudinary.com/users/register/free" target="_blank">here</Link>.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Cloudinary app

<Link href="https://hygraph.com/marketplace/apps/hygraph-cloudinary-app" target="_blank">Click here</Link> to install the Cloudinary App on Hygraph, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x96hhu4n07vx29st0ju3" caption="Cloudinary installation" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to the **Configure Cloudinary** section of your Hygraph project.
2. Fill in the `Cloud Name` and `API Key` fields using the information available in the **Account Details** section of <Link href="https://cloudinary.com/console/" target="_blank">your Cloudinary account</Link>.
3. Click on the `Submit` button. A pop-up notification in the lower right corner of the screen will indicate that the changes have been saved.

## Add the Cloudinary asset field to a model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x94gjarj07w58zrzu6bo" caption="Add the Cloudinary asset field to a model" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **Cloudinary Asset** field to.
3. Select the **Cloudinary Asset** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`. This screen allows you to control different properties of your **Cloudinary asset** field: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
5. Click on the `Create` button.

## Use the Cloudinary asset field in Hygraph

To use the Cloudinary asset field in Hygraph, navigate to the **Content Editor** and select the model you added the **Cloudinary Asset** field to.

1. Click on the `Add from Cloudinary` button to select an asset hosted in your Cloudinary account.

    ![Cloudinary asset field in the Hygraph content editor](/images/docs/integrations/cloudinary/cloudinary-asset-picker.png)

2. In the Cloudinary Media Library, select the asset, and then click **Add & close**. You can also click **Upload** to select files from your computer and upload them to the linked Cloudinary account. You can then choose to add those files in the content entry.

    ![Add Cloudinary asset](/images/docs/integrations/cloudinary/cloudinary-asset-add.png)

If your `Cloudinary asset picker` schema configuration allows multiple values, you will be able to select multiple assets in a content entry as a result. You can use the six-dot handle to reorder these assets by dragging and dropping them in the order you want:

![Reorder Cloudinary assets](/images/docs/integrations/cloudinary/cloudinary-reorderassets.png)

You can also click on the `X` on the right of an asset card to remove it form the list.

<Alert theme="warning">

If you wish to link data from an existing Cloudinary account using a script, please read <Link href="https://cloudinary.com/documentation/media_library_widget" target="_blank">this document</Link>.

</Alert>

## Query your Cloudinary assets

You can query the Cloudinary assets used in your Hygraph project using our [API Playground,](/docs/api-reference/basics/api-playground) which you will find on the left side menu of your Hygraph project.

![Cloudinary assets query in our API Playground](/images/docs/integrations/cloudinary/cloudinary-api-playground.png)

Find additional information on how to query content in Hygraph [here](/docs/getting-started/api-playground-queries).

### Update Cloudinary field data

In some cases it can be necessary to update Cloudinary data stored in Hygraph, due to an event that happened in Cloudinary - such as an update to an asset's metadata. You can use the following flow to do this:

1. Create a simple function, such as a lambda, that can catch a webhook from Cloudinary.
2. Using the information in the webhook, such as the asset ID, find the corresponding entries in Hygraph that reference this asset. You can use [`JSON` filters](/docs/api-reference/content-api/filtering#json-filtering) to search for IDs in the underlying Cloudinary fields. It's also possible to filter on Cloudinary fields inside components, using the [basic](/docs/api-reference/content-api/filtering#basic-component) and [modular component filters](/docs/api-reference/content-api/filtering#modular-component).
3. Update the fields in Hygraph using [mutations](/docs/api-reference/content-api/mutations).

<a id="migration"></a>

## How to replace the UIX with the new app

<Alert theme="warning">

Before you delete the Cloudinary UIX, make sure that you have the **Cloud Name** and **API Key** in a safe place. You will need them to setup the app.

</Alert>

Here is the step-by-step guide on how to install the Cloudinary app for Hygraph to replace the UIX.

1. Remove the Cloudinary UIX from your project. To do that, go to **Settings > UI Extensions**. Click on the three dots, then click on the `Remove` button.
2. <Link href="https://app.hygraph.com/apps/cloudinary/new" target="_blank"><strong>Click here</strong></Link> to install the Cloudinary app.
3. Select your project in the dropdown, then click on `Add App`.
4. Enter the `Cloud Name` and `API Key` in the fields, then click `Submit` to save the settings.

![Cloudinary migration - Configuration](/images/docs/integrations/cloudinary/cloudinary-migration-configure.png)

5. Now, go to the **Schema** editor and open the model that you are using the **Cloudinary asset** field in.
6. Click on `Edit Field`. On the left top corner of the dialog, click on the dropdown, then click on `Cloudinary asset`. Finally, click on the `Update` button.

![Cloudinary migration - Select asset](/images/docs/integrations/cloudinary/cloudinary-migration-asset.png)

## Resources

- Click <Link href="https://cloudinary.com/documentation" target="_blank">here</Link> to access Cloudinary's online documentation.


---
# Connect your Hygraph project to commercetools

Source: https://hygraph.com/docs/integrations/connect-commercetools

**commercetools** is a cloud-based headless commerce platform that provides APIs to power e-commerce sales and similar functions for large businesses.

## What you can do with the Hygraph-commercetools integration

With this app you can continue to use commercetools as your preferred headless commerce solution for products and eCommerce assets. By installing the commercetools app, you can bring your commercetools products into Hygraph projects with the rest of your content.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **commercetools** account. If you don't have one yet, you can get one <Link href="https://commercetools.com/" target="_blank">here</Link>.
- You must have created a project in your commercetools account. <Link href="https://docs.commercetools.com/merchant-center/organizations-teams-projects#create-a-project" target="_blank">Here</Link> is some information on how to get started.
- You must have `Storefront search` indexing status set to active. In order to do this, access your commercetools project, navigate to **Settings > Project Settings > Storefront search**, and set the `Indexing status` switch to **on**.
- You must create an API Client and get the `Project key`, `Client ID`, `Client Secret` and the `API URL` from your commercetools project. In order to do this, access your commercetools project and navigate to **Settings > Developer settings > API Clients**. Click on the `+ Create new API client` button, located at the upper right corner of the form. Type in a `Name` of your choice and use the `Scopes` dropdown to select the `Read only client` option, then click on `Create API client`. <Link href="https://docs.commercetools.com/getting-started/create-api-client" target="_blank">Here</Link> you will find detailed in formation on how to do this.

  <Alert theme="warning">

  **Do not close the new API client screen that displays as a result before you finish the installation process**, as you cannot access it again and you will need the data shown there to configure the commercetools app in Hygraph.

  </Alert>

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

## Install the commercetools app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-commercetools-app" target="_blank">here</Link> to install the commercetools App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/K8TBMqCKQCqiHdRLJggh" caption="Install commercetools app" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add app` button. You should be redirected to the **Configure commercetools** section of your Hygraph project dashboard.
2. Fill in the `Project key`, `Client ID`, `Client Secret` and the `API URL`. Information on how to get these is listed under the [prerequisites for this integration](/docs/integrations/connect-commercetools#prerequisites-to-use-this-integration).
3. Click on the `Save` button. A pop-up notification in the lower right corner of the screen will indicate that the changes have been saved.

## Add the commercetools picker to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/BaOLZGYCQZ2nS1iO6VXj" caption="Add commercetools product field" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **commercetools picker** field to and click on it.
3. Select the **commercetools picker** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`. This screen allows you to control different properties of your **commercetools picker** field: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
5. Click on the `Add` button.

## Use commercetools in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/wT8IyMcyTJy9IAp4JC8R" caption="Use commercetools in Hygraph" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **commercetools picker** field for.
3. Click on the `+ Add entry` button or, alternatively, edit an existing entry.
4. Locate the **commercetools picker** section of the screen and click on `Select product from commercetools`. As a result, a new screen will display, showing the products available in your commercetools store.
5. Select the product you wish to add to the entry using the checkboxes, then click on the `Select products` button. Optionally, you can use the search filters to find the products you are looking for.
6. Now that the product has been added to the entry, you can click on `Save` or `Save & Publish`, as needed.

<Alert theme="warning">

Products in your **commercetools** project need to be in status `Published` in order to display in the product picker.

</Alert>

## Resources

- <Link href="https://docs.commercetools.com/docs/" target="_blank">commercetools documentation</Link>


---
# Connect your Hygraph project to Crowdin

Source: https://hygraph.com/docs/integrations/connect-crowdin

<Link href="https://crowdin.com/" target="_blank">Crowdin</Link> is a cloud-based localization software for teams and businesses. You can automate the translation of all your content, and manage source copy and translations from design to production with this tool. Crowdin has 2M+ user accounts and hosts hundreds of localization projects.

It has two products:

- **crowdin.com** for teams and personal use with all the essential features for continuous localization included.
- **Crowdin Enterprise** for organizations that require high customization and enterprise-level security features.

## What you can do with the Hygraph-Crowdin integration

With this app, you can streamline the localization process of your content, directly from within Hygraph. It will help you manage all of your multilingual content effectively, keeping your workflow agile.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **Crowdin** account. If you don't have one yet, you can get one <Link href="https://accounts.crowdin.com/register" target="_blank">here</Link>.
- You must have created a **project** in your Crowdin account, and an **API key**.

<Alert theme="warning">

The way to access the information you need from your Crowdin account in order to configure this integration depends on whether you have a **Crowdin.com** or a **Crowdin Enterprise** account:

- **Crowdin.com:** Here is some information on how to access your <Link href="https://support.crowdin.com/creating-project/" target="_blank">Crowdin Project ID</Link>, and how to generate your <Link href="https://support.crowdin.com/account-settings/#api" target="_blank">Crowdin Access Token</Link>.

- **Crowdin Enterprise:** Here is some information on how to access your <Link href="https://support.crowdin.com/enterprise/project-settings/#details" target="_blank">Crowdin Enterprise Project ID</Link>, and how to generate your <Link href="https://support.crowdin.com/enterprise/personal-access-tokens/" target="_blank">Crowdin Enterprise Access Token</Link>.

</Alert>

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

## Install the Crowdin App

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-crowdin-app" target="_blank">here</Link> to install the Crowdin App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/5FUTop62TiaLjLXnm3gg" caption="Install Crowdin app" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to the **Configure Crowdin** section of your Hygraph project.
2. Fill in the `API Key` and the `Project ID`, you can leave the `Crowdin Enterprise Organization Name` field blank.
3. Click on the `Save` button. A pop-up notification in the lower right corner of the screen will indicate that the changes have been saved.

## Sync your content

Once the app is installed, you must log into your **Crowdin** account to set up the integration on their end to sync the content. Crowdin offers a <Link href="https://store.crowdin.com/hygraph" target="_blank">detailed step-by-step guide</Link> on how to do this but, essentially, you will follow these steps:

1. Go to the **Crowdin marketplace** and find the **Hygraph** connector under `Applications`. You can use <Link href="https://crowdin.com/store/apps/hygraph" target="_blank">this link</Link>.
2. Install **Hygraph**.
3. If you haven't set up a project yet, go to your **Crowdin workspace** and <Link href="https://support.crowdin.com/creating-project/" target="_blank">create one</Link>. If you already have a project, please skip this step.
4. In your **Crowdin** project, navigate to the **integrations** section, look for the **Hygraph** integration, and click on it.
5. Add your credentials to enable **Crowdin** to connect to your **Hygraph** instance, then click on `Login with Hygraph`. You will find these credentials in your **Hygraph project** by navigating to **Project settings**.

   | Crowdin              | Hygraph                                                 |
   | -------------------- | ------------------------------------------------------- |
   | Project ID           | Project Settings > General > Project                    |
   | Environment URL      | Project Settings > API Access > Endpoints > Content API |
   | Permanent Auth Token | Project Settings > API Access > Permanent Auth Tokens   |

   **Permanent Auth Token**

   You will need to create a Permanent Auth Token for this integration. To do this, go to your Hygraph project, navigate to **Project Settings > API Access > Permanent Auth Tokens,** and click on `Add`.

   Scroll down to the **Content API** section and add all permissions, except `Delete model`.

   Then, scroll down to the **Management API** section and click on the `No, I'll configure my own permissions` button, then click on `Edit permissions` and select the following:

   - Can see schema view.
   - Update published entries.
   - Read locales.
   - Update locales.
   - Read public content views.
   - Update existing non-published entries.
   - Create locales.
   - Read existing environments.
   - Read stages.
   - Read existing models.

    <Alert theme="warning">

   Easily find these Management API permissions using **Cmd/Ctrl + F**.

    </Alert>

6. After adding your **Hygraph** credentials in **Crowdin**, click on `Settings` - located on the upper right corner of the Crowdin-Hygraph integration panel - and use the dropdown to select the language to be mapped in Hygraph. Then, scroll down to **Entries display settings**, and select how the models will be displayed using the dropdowns. Finalize this process by clicking on `Save`.

   <Alert theme="warning">

   In order to successfully map a language, you must have it set up in your Hygraph project as well as in Crowdin. Click [here](/docs/developer-guides/project/manage-project-locales) for detailed information on how to manage your project locales.

   </Alert>

7. Select the files to be synced to Crowdin from the Hygraph panel using the checkboxes, and finally click on the `Sync to Crowdin` button.

As a result of this integration, your content in Hygraph will be synced with your Crowdin project. The content in Hygraph will then be displayed in Crowdin to be translated and, as translations advance, you will see this reflected [in the content entry's progress bar](/docs/integrations/connect-crowdin#crowdin-in-your-hygraph-content-entry), under the **Crowdin** title.

## Add the Crowdin sidebar widget to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/8cRSJQl0RAO5fhssXZpw" caption="Add Crowdin sidebar widget" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **Crowdin** widget to and click on it, then select the `Sidebar` tab.
3. Select the **Crowdin** widget from the **Widgets** right sidebar.
4. The `Display name` and `Description` fields will already be complete, but you can optionally edit them.
5. Click on the `Add` button.

## Crowdin in your Hygraph content entry

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/ffBH8G8cQ4aT2sGCWafN" caption="Use Crowdin in content entry" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Crowdin** widget for.
3. Create an entry or edit an existing one. You will find the **Crowdin** progress bar on the sidebar of your entry. The progress bar displays different colors for how much of your content translations have been finalized, and how much of the work is still in progress.

<Alert theme="warning">

The placement of the Crowdin widget in the sidebar depends on the order within the model that you gave it in the Schema builder. Click [here](/docs/developer-guides/content/customize-sidebar#reordering-widgets) for more information.

</Alert>

## Resources

- <Link href="https://store.crowdin.com/hygraph" target="_blank">Hygraph connector for Crowdin</Link>
- <Link href="https://support.crowdin.com/creating-project/" target="_blank">How to create a Crowdin project</Link>
- <Link href="https://support.crowdin.com/translation-process-overview/" target="_blank">Crowdin knowledge base</Link>
- <Link href="https://support.crowdin.com/enterprise/overview/" target="_blank">Crowdin enterprise knowledge base</Link>
- <Link href="https://support.crowdin.com/translation-process-overview/" target="_blank">Crowdin translation process overview</Link>


---
# Connect your Hygraph project to DeepL

Source: https://hygraph.com/docs/integrations/connect-deepl

**DeepL** is an advanced machine translation service that uses artificial intelligence and neural networks to provide highly accurate translations. 

## What you can do with the Hygraph-DeepL integration

With the **Hygraph-DeepL integration**, editorial teams can translate the localized fields in a content entry with a single click.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project).
- You must have a **DeepL** account. If you don't have one, you can create one <Link href="https://auth.deepl.com/login" target="_blank">here</Link>.
- You must have a <Link href="https://support.deepl.com/hc/en-us/articles/360020695820-API-Key-for-DeepL-s-API#:~:text=To%20find%20your%20API%20keys,Deactivating%20obsolete%20or%20corrupted%20keys" target="_blank">DeepL API Key</Link>.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the DeepL app

Click <Link href="https://app.hygraph.com/apps/deepl-app/new" target="_blank">here</Link> to install the **DeepL** App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cm85ufz6a8fmd07w49r91aoyy" caption="Install DeepL app" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click on `Install app`.
2. The permissions pop-up will display. Click on `Authorize app` to continue. You will be redirected to the configuration screen.
3. Fill in the `API Key` on the **Configure DeepL** screen and click `Validate`.
4. After the system validates the API Key, you need to map locales. Use the dropdowns to select the DeepL target languages that match your Hygraph locales. You can also click `Auto map` to do this automatically.
5. Click `Update` to save the mapped locales and finalize the installation process.

## Add DeepL to the sidebar of a model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cm85uom8g8yx207utjq756qul" caption="Add DeepL to content sidebar" />

1. Navigate to the **Schema builder** and select the model you want to add the widget to.
2. Select the **Sidebar** tab.
3. Click on the **DeepL translate** card on the right sidebar.
4. Give the sidebar widget a display name. You can also optionally give it a description.
5. Click `Add` to save.

If you now go to the Content editor, find the view for that model, and open a content entry, you will see the **DeepL sidebar widget** to the right of the screen.

The widget automatically shows all locales that are the active and shown for that entry. You can select which locales to translate by using the [Localizations sidebar widget](/docs/developer-guides/content/content-localization#show-or-hide-translated-fields) to show or hide locales.

## Translate content with DeepL

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cm85urrnq93zv07w42tdpwe39" caption="Translate content with DeepL" />

DeepL allows you to automatically translate the localized field in your content entry with one click.

Simply click `Translate all` on your **DeepL sidebar widget** located to the right of the screen. If the localized fields already contain a translation, the DeepL translation will overwrite it. A warning indicating this will display, and you need to click `Yes, translate` to continue.

<Alert theme="info" title="Pro Tip">

The DeepL app automatically detects the locales that you have set as active and shown for the content entry.

You can select which locales to translate by using the [Localizations sidebar widget](/docs/developer-guides/content/content-localization#show-or-hide-translated-fields) to show or hide locales.

</Alert>

After a few seconds, the localized fields will become populated with the translations, one by one.

Once the translation is finished, a success message will display if there were no errors. If there were any errors, the message will indicate which locales were affected.

## Troubleshooting

### I can't see the DeepL sidebar widget

- Check that the widget has been added to the sidebar of the model you are creating content for.
- Check that locales other than the default one have been added and are currently shown for the content entry you're working on. You can find information on how to add, show or hide translations [here](/docs/developer-guides/content/content-localization).


---
# Connect your Hygraph project to EasyTranslate

Source: https://hygraph.com/docs/integrations/connect-easytranslate

**EasyTranslate**'s language solutions platform gives you easy access to professional, high-quality translation, interpretation, and localization services for any market. Thousands of businesses from all industries - from small eCommerce to large enterprises - use EasyTranslate's software to generate content from simple keywords, recruit freelance translators or automate translation flows from various platforms.

## What you can do with the Hygraph-EasyTranslate integration

- The **Hygraph-EasyTranslate integration** allows your team to sync/submit your content from Hygraph to EasyTranslate, where you can localize your content either automatically or done by your team, then import it back into your CMS seamlessly

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project).
- You must have an **EasyTranslate** account. If you don't have one, you can create one <Link href="https://platform.easytranslate.com/en/freemium-start" target="_blank">here</Link>.
- You must have an EasyTranslate `Personal access token`. You will find it in your EasyTranslate account by navigating to **Integrations > Hygraph**.
- You must have a `Library` created in EasyTranslate. <Link href="https://knowledge.easytranslate.com/how-to-create-a-library" target="_blank">This document</Link> explains how to create one.
- You must have a `Team` set up in EasyTranslate. <Link href="https://www.youtube.com/watch?v=58hG9PW3elM&t=26s" target="_blank">This video</Link> shows you how to set up your translators team.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the EasyTranslate app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-easytranslate-app" target="_blank">here</Link> to install the **EasyTranslate** App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/KfKS3fkBQLSeQcJR2a5F" caption="Install EasyTranslate app" />

1. Use the the dropdowns to select which project and environment you want to install the app in, then click on the `Install App` button. You should be redirected to your **Hygraph** project dashboard.
2. Click on `Authorize app` on the permissions screen.
3. Fill in the following information:
   - `Personal access token`: You can find this information in your **EasyTranslate** account by navigating to **Integrations > Hygraph**. Once you add this token, you can use the dropdowns to select a team and library.
   - `Team`: Use the the dropdown to select which team you want to configure the app for. <Link href="https://www.youtube.com/watch?v=58hG9PW3elM&t=26s" target="_blank">Here's</Link> some information on how to set up a translators team in your EasyTranslate account.
   - `Library`: Use the the dropdown to select which library you want to configure the app for. <Link href="https://knowledge.easytranslate.com/how-to-create-a-library" target="_blank">Here's</Link> some information on how to create a library in your EasyTranslate account.
4. Select at least one of the listed `Translatable models` to use **EasyTranslate** in. This information can be edited later by going to the **Apps** section of your Hygraph project, then clicking on the pencil icon on the EasyTranslate card to edit the details.
5. Click on the `Save` button.

## Use EasyTranslate in your Hygraph project

As you create content, it will display in the **EasyTranslate** app view of the **Content editor**. From there, you will be able to [send your content for translation](/docs/integrations/connect-easytranslate#send-for-translation) to **EasyTranslate**, then [sync](/docs/integrations/connect-easytranslate#sync) those translations with your **Hygraph** content.

<Alert theme="warning">

Please note that only the content created using the <b>Model</b> that you selected during the <b>EasyTranslate installation process</b> will display on this list.

You can edit this from your <b>Hygraph project</b> by navigating to <b>Apps > EasyTranslate</b>, clicking on the pencil icon to edit, then using the checkboxes to select the models you want.

</Alert>

Finally, after syncing the content, you will be able to [view the translated content](/docs/integrations/connect-easytranslate#view-translations) normally by accessing the **Content editor**.

## Send for translation

There are two ways to send your content for translation:

- [Send multiple entries at the same time using the app view form](/docs/integrations/connect-easytranslate#send-multiple-entries)
- [Send a single entry from inside the entry edit view](/docs/integrations/connect-easytranslate#send-single-entry)

**The following fields are supported to be exported to EasyTranslate:**

- Single-line text
- Multi-line text
- Markdown
- Richtext
- Slug

Export is also supported for Basic and Modular Components, but only for the supported field types.

Take into account that only localizable fields can be submitted to EasyTranslate. So the fields must be set as localized fields when added to the model.

![Localized field checkbox](/images/docs/integrations/lokalise/lokalise-localizefield.png)

You will find the `Localized field` checkbox at the bottom of the field details screen, which displays when you create or edit a field in the **Schema** editor.

### Send multiple entries

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/EgTFguWbTRm8vEHLblWJ" caption="Send multiple entries to translate" />

1. Navigate to the **content editor**.
2. Find **EasyTranslate** under the **App views** section of the right sidebar.
3. Use the checkboxes to select the desired content from the list, and send it to **EasyTranslate** by clicking on `Send for Translation` at the top right of the form. It is also possible to filter content entries by `Model` and `Locale` using the dropdowns at the top of the form.

The system then sends the content to EasyTranslate for translation. After work on that content is finished, you can sync the content to bring those translations to Hygraph.

### Send single entry

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/mm0k3A7RvGPw7rInzowf" caption="Send single entry to translate" />

1. Navigate to the **content editor**.
2. Find **EasyTranslate** under the **App views** section of the right sidebar.
3. Find the entry you want to send and click on the pencil icon to access the edit view.
4. Click on the `Send for translation` button on the sidebar.

The system then sends the content to EasyTranslate for translation. After work on that content is finished, you can sync the content to bring those translations to Hygraph.

## Sync

After [sending content for translation](/docs/integrations/connect-easytranslate#send-for-translation) to **EasyTranslate**, it will be <Link href="https://knowledge.easytranslate.com/for-freelancers" target="_blank">translated and saved there</Link>. You can then bring that content back to **Hygraph** by syncing.

There are two ways of syncing your content:

- [Sync multiple entries at the same time using the app view form](/docs/integrations/connect-easytranslate#sync-multiple-entries)
- [Sync a single entry from inside the entry edit view](/docs/integrations/connect-easytranslate#sync-single-entry)

### Sync multiple entries

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/olT4RvPzRlur7ppJgu56" caption="Sync multiple translations" />

1. Navigate to the **EasyTranslate** app view of the **Content editor**.
2. Use the checkboxes to select the entries whose translations you want to sync, then click on the `Sync` button at the top right of the form.
3. The form will refresh and the entries will now contain the translated content as localizations.

### Sync single entry

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/ytcNDKgSRTWC6buKTByF" caption="Sync single translation" />

1. Navigate to the **EasyTranslate** app view of the **Content editor**.
2. Find the entry you want to sync and click on the pencil icon to access the edit view.
3. Click on the `Sync with EasyTranslate` button on the sidebar.
4. The localized fields will now display the translated content.
5. Click on `Save` or `Save and Publish`.

## View translations

1. Navigate to the **content editor**, and select the view of the model you included **EasyTranslate** in.
2. Edit an entry that you synced a translation for by clicking on the pencil icon. The content will display at the center of the screen.
3. You will find the `Localizations` section in the right sidebar. You have the following options:
   1. Click on the `+` icon to add a translation.
   2. Click on the trash icon to delete a translation.
   3. Click on the eye icon to view a translation in the editor.

![View translations](/images/docs/integrations/lokalise/lokalize-add-visualize.png)

## Troubleshooting

If the **Content Editor** displays the message `This model has no localized fields` under localizations in the sidebar, while the **Schema Editor** has localizations configured, go to **Project settings > Locales**. There, make sure your project has at least two languages configured.

![Locales in project settings](/images/docs/integrations/lokalise/lokalise-settings-locales.png)

If you have only one language configured there, select another language for localizations using the `Display name` dropdown, then click on `Add`.

<Alert theme="warning">

Please note that free plans can have a maximum of 2 locales.

</Alert>

## Resources

- <Link href="https://knowledge.easytranslate.com/" target="_blank">EasyTranslate knowledge base</Link>.


---
# Connect your Hygraph project to Gatsby Cloud

Source: https://hygraph.com/docs/integrations/connect-gatsby-cloud

Using Gatsby Cloud with your Hygraph powered Gatsby site enables the following:

- Preview content changes using lightning fast **CMS Preview** builds. Any content changes on the **Draft** stage will automatically be updated and ready to preview in seconds.
- Incremental production builds that only rebuild the required changes. This results in faster builds and deployments for Hygraph content on your **Published** stage.

## Prerequisites

This guide assumes the following:

1. You have a Hygraph project. If not, create one <Link href="https://app.hygraph.com/" target="_blank">here</Link>.
2. You have a pre-existing Gatsby project that uses <Link href="https://github.com/hygraph/gatsby-source-graphcms" target="_blank"><code>gatsby-source-graphcms</code></Link> on GitHub or GitLab.
3. You are familiar with creating a Gatsby Cloud site from an existing GitHub or GitLab repository. Read <Link href="https://www.gatsbyjs.com/docs/sourcing-from-graphcms/#headless-the-graphcms-way" target="_blank">this guide</Link> for instructions on how to do this.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## 1. Create a new Gatsby Cloud site

If you have a pre-existing Hygraph powered Gatsby site in Gatsby Cloud, you can skip to [step 2](#2-gathering-required-gatsby-cloud-site-values). In Gatsby Cloud, create a new site by importing your pre-existing Gatsby project from a GitHub repository. You can follow <Link href="https://www.gatsbyjs.com/docs/sourcing-from-graphcms/#headless-the-graphcms-way" target="_blank">this guide</Link> for instructions on how to do this.

During the setup process, you will be asked to provide any environment variables required for your Gatsby site to build. This will likely include the following:

- Your Hygraph project URL (**required**).
- If configured, a [PAT](/docs/api-reference/basics/authorization#permanent-auth-tokens) (Permanent Auth Token) for the project.

Once configured, your new Gatsby Cloud site will build and be accessible in your dashboard.

## 2. Gathering required Gatsby Cloud site values

Before we can enable the Gatsby Cloud integration on our Hygraph project, we need some details from our newly initialized Gatsby Cloud site.

Form the Gatsby Cloud dashboard, go to the site you want to work with, click **Site Settings**.

You will need to make note of your project's **Prefix** as that will be needed for the Hygraph setup.

![Gatsby Cloud project fields.png](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/pZecG2oSOmXcJsyRximx)

Now navigate to the **Webhook** section. In order to trigger new Gatsby Cloud builds for both the production and Preview instances, we need both the **Preview Webhook** and **Builds Webhook** URLs. These will be required during the Gatsby Cloud integration setup.

Be sure to check that CMS Preview builds are enabled to your Gatsby Site project. This can be done in the **Preview** section of the **Site Settings** page. _This is required!_

![Gatsby Cloud enable CMS Previews.png](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/Tg9ftIyrSkaMCQRF7x2Y)

## 3. Configure Gatsby Cloud for Hygraph

![Hygraph Gatsby Cloud integration.png](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/Sak9Yqn3QNaQzHaFe8w8)

In your Hygraph project dashboard, navigate to **Settings** and then **Integrations**. From here click **Gatsby Cloud** and then **Enable**.

![Hygraph Gatsby Cloud enable.png](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/CCfgb1SNRTWjPV5cZDb4)

Populate the form fields with the values we just took from our Gatsby Cloud site and click **Enable**.

![Hygraph Gatsby Cloud configuration.png](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cq09ucpBTrSRCJBR4xpb)

## 4. Enjoy automated preview and incremental deploys!

Once successfully enabled, your project will:

- Trigger a Gatsby Cloud CMS Preview build whenever you save **Draft** content changes.
- Trigger a Gatsby Cloud incremental build deployment whenever you push content changes to the **Published** stage.

![Hygraph Gatsby Cloud preview button.png](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/Hiv0F1mpSkSTf8oqQoEZ)
Your content editing experience will now include a preview button direct to your Gatsby Cloud CMS Preview instance. CMS Preview builds are fast and the instance should automatically update in seconds.


---
# Connect your Hygraph project to Imgix

Source: https://hygraph.com/docs/integrations/connect-imgix

**Imgix** lets you create, transform, and optimize images and videos.

## What you can do with the Hygraph-Imgix integration

With the Imgix app, you can serve assets from your Hygraph project and from other Imgix sources to add to your content.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a Imgix account. If you don't have one yet, you can create one <Link href="https://dashboard.imgix.com/sign-up" target="_blank">here</Link>.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Configure a source

The first thing we need to do is configure a source in your Imgix account. The configuration flow will vary depending on whether you want to serve assets from your Hygraph project or from one of the other configurable sources.

### Using assets from Hygraph

1. Create a new Imgix source, selecting `Web Folder` as a `Storage Type`. <Link href="https://docs.imgix.com/getting-started/setup/creating-sources/web-folder" target="_blank">This document</Link> contains more details about the `Web Folder` source.
2. Enter the base URL for your Imgix source. If your Hygraph project is using the [Legacy asset system](/docs/api-reference/assets/assets-overview#which-asset-system-does-my-project-use), you will need to use `https://media.graphassets.com/` as the base URL. If your project uses the Hygraph Asset Management system, follow the instructions below to obtain the URL, go to the **Assets** tab in the Hygraph app and right click any asset thumbnail, then select `Copy Image Address` at the bottom of the preview. Keep the part before `/output=...` and delete the rest.

      **Base URL example:** If your copied URL is
      ```
      https://eu-central-1-shared-euc1-02.graphassets.com/clv45iyzm039407umd5w7aemt/output=format:jpg/resize=width:59,height:59,fit:crop/clw6dt8hndhuu07w6tcaqt9h3
      ```
      You should use the following as the base URL:
      ```
      https://eu-central-1-shared-euc1-02.graphassets.com/clv45iyzm039407umd5w7aemt
      ```
3. Use the default Imgix subdomain or configure your own, and press the `Deploy Source` button.

<Alert theme="info" title="Would you like to know more?">
Checkout <Link href="https://docs.imgix.com/getting-started/setup/creating-sources/web-folder" target="_blank">Imgix's documentation</Link> for more detailed instructions on configuring the Web Folder source.
</Alert>

### Using assets from other sources

This flow is different depending on the selected source. Check out <Link href="https://docs.imgix.com/getting-started/setup/creating-sources" target="_blank">Imgix's documentation</Link> for instructions on configuring your Imgix source.

## Install the Imgix app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-imgix-app" target="_blank">here</Link> to install the Imgix App on **Hygraph**, then follow these steps:

The installation flow will vary depending on whether you want to serve assets from your Hygraph project or from one of the other configurable sources.

### Install using a Hygraph source

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/0T5z0FITHCdxhTI2Ws1L" caption="Install Imgix Hygraph source" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click `Install app`.
2. The permissions pop-up will display. Clicking `Authorize app` finishes the installation and takes you to the app configuration screen.
3. Next, you need to configure the app. To do that, you first need to select `Webfolder` as a source type in the Hygraph app configuration - this should be the default value.
4. Enter your imgix source domain in the `Source URL` field, prefixed with `https://`.
      <Alert theme="info" title="Source URL example">
      If you used `my-assets` during the creation of your Imgix source, then the `Source URL` would be `https://my-assets.imgix.net`.
      </Alert>
5. Click `Save config settings` to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

### Install using other sources

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/2OxKmnVRCrBIAxtaHBqg" caption="Install Imgix other sources" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click `Install app`.
2. The permissions pop-up will display. Clicking `Authorize app` finishes the installation and takes you to the app configuration screen.
3. Next, you need to configure the app. To do that, you first need to select `Other` as a source type in the Hygraph app configuration.
4. Enter your imgix source domain in the `Source URL` field, prefixed with `https://`.
      <Alert theme="info" title="Source URL example">
      If you used `my-assets` during the creation of your Imgix source, then the `Source URL` would be `https://my-assets.imgix.net`.
      </Alert>
5. Fill in the `API Key` field with an API key obtained from your Imgix account.
      <Alert theme="info" title="Pro Tip">
      To create a new imgix API key, use the dropdown menu in the top-right corner of the Imgix dashboard, then go to `API Keys` and select `Generate new key`.

      The permission that is necessary for the app to access your assets is `Asset Manager Browse`.
      </Alert>
6. Fill in the Source ID field with the ID if your Imgix source. To find your source ID, go to your Imgix dashboard, navigate to `Sources`, and select `View` on the source you want. You will find the source ID under the `Source ID` field.
7. Click `Save config settings` to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

## Add the Imgix field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/AWAvsbx0T4O7T2u20W0A" caption="Add Imgix asset field" />

1. Navigate to the **Schema** builder.
2. Select the model that you want to add the **Imgix** field to.
3. Select the **Imgix** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your Akeneo field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the `Field options` section.
6. Click `Add`.

## Use Imgix in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/UXbWlBhMQhywACP7GzuY" caption="Use Imgix in Hygraph" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Imgix** for.
3. Click `+ Add entry` to create a new entry or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Imgix** section of the screen and click on `Add assets`. This opens a new screen where you can select and add assets to your Hygraph content entry.
5. Select the asset(s) you want, and then click `Add selected assets`. If your **Imgix Field** configuration allows multiple values, you will be able to select multiple assets.
6. After selecting the asset(s) you want and returning to the content entry, your selection will display on the list. You can optionally use the six dots icon to drag and drop the assets on the list to organize them in the order you want, or click on the `X` on the right of an asset card to remove it form the list.
7. Finally, click `Save` or `Save & Publish`, as needed.

## Troubleshooting

<Alert theme="warning">

These are known limitations due to the way Hygraph & Imgix work. Please read these carefully before using this app.

</Alert>

- If you replace an asset file in Hygraph, it will not update and show the old version instead. Please delete the asset completely and create a new one if you want to change the displayed image.

- Sometimes, fields might get clipped and the button to add or change assets might not be visible. Refreshing the page resolves the issue. This a rare but known bug for Hygraph apps. If the issue still persists after a refresh open an issue.

## Resources

- <Link href="https://docs.imgix.com/" target="_blank">imgix documentation</Link>


---
# Connect your Hygraph project to Lokalise

Source: https://hygraph.com/docs/integrations/connect-lokalise

**Lokalise** is a localization management platform where teams can easily build and manage workflows for multiple locales and translations of existing content. It enables teams to build collaborative workflows around localization, ensure high quality translations are pushed live, and create new locales for a wide range of digital products, from applications to websites.

## What you can do with the Hygraph-Lokalise integration

- With the **Hygraph-Lokalise integration**, teams can simplify their workflows between **Lokalise** and **Hygraph** by creating bulk imports and exports of content and easily manage multiple locales for their digital products through a dedicated interface within **Hygraph**.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project).
- You must have a **Lokalise** account. If you don't have one, you can create one <Link href="https://app.lokalise.com/signup" target="_blank">here</Link>.
- You must have a <Link href="https://docs.lokalise.com/en/articles/1400460-projects" target="_blank">Lokalise project</Link>. The <Link href="https://docs.lokalise.com/en/articles/2800192-document-file-support" target="_blank">project type</Link> must be **Software localization**, and you must select a base language for your project in your project settings.
- You must create a <Link href="https://docs.lokalise.com/en/articles/1929556-api-tokens" target="_blank">Lokalise API Token</Link>.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Lokalise app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-lokalise-app" target="_blank">here</Link> to install the **Lokalise** App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9c5hu5107vx3dqc9lgs" caption="Lokalise installation" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to your **Hygraph** project dashboard.
2. Fill in the `API token` and the `Project ID`. This information can be found in your **Lokalise** account. The **Hygraph** UI provides links that show you how to get the information you need next to each requested field.
3. Select at least one model to use **Lokalise** in. This information can be edited later by going to the **Apps** section of your Hygraph project, then clicking on the pencil icon in the Lokalise card to edit the details.
4. Click on the `Save` button.

## Use Lokalise in your Hygraph project

As you create content, it will display in the **Lokalise** section of the **Content editor**, under **App views**. From there, you will be able to [export](/docs/integrations/connect-lokalise#export-translation) content to **Lokalise** to be translated, then [import](/docs/integrations/connect-lokalise#import-translation) those translations into **Hygraph**.

<Alert theme="warning">

Please note that only the content created using the <b>Model</b> that you selected during the <b>Lokalise installation process</b> will be displayed on this list.

You can edit this from your <b>Hygraph project</b> by navigating to <b>Apps > Lokalise</b>, clicking on the pencil icon to edit, then using the checkboxes to select the desired models.

</Alert>

Finally, after the process has been completed, you will be able to [view the translated content](/docs/integrations/connect-lokalise#view-translations) normally by accessing the **Content editor**.

Take into account that only localizable fields can be submitted to Lokalise. So the fields must be set as localized fields when added to the model.

![Localized field checkbox](/images/docs/integrations/lokalise/lokalise-localizefield.png)

You will find the `Localized field` checkbox at the bottom of the field details screen, which displays when you create or edit a field in the **Schema** editor.

### Export translation

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x98djasa07w5b56lbly8" caption="Submit to translate" />

1. Navigate to the **content editor**.
2. Select **Lokalise** under the **App views** section of the right sidebar.
3. Use the checkboxes to select the desired content from the list, and send it to **Lokalise** by clicking on the `Submit to Translate` link at the top of the form.
4. A pop-up will display, where you need to select the locales to export. Select the necessary checkboxes, and click on the `Export translation` button.
5. The translation status will change to **In progress**, and you will be able to find the content ready to translate in your **Lokalise** account.

If the content is exported successfully, a green message will pop up in the lower right corner of the screen indicating this. If it fails, a red message will be displayed in the same place indicating that the submit was unsuccessful.

**The following fields are supported to be exported to Lokalise:**

- Single-line text
- Multi-line text
- Markdown
- Richtext
- Slug

Export is also supported for Basic and Modular Components, but only for the supported field types.

<Alert theme="info">

You can copy the entry ID and use it on Lokalise to filter the entry there and easily find it.

</Alert>

### Import translation

After [exporting](/docs/integrations/connect-lokalise#export-translation) content to **Lokalise**, it will be <Link href="https://docs.lokalise.com/en/collections/2909016-translate-and-collaborate" target="_blank">translated and saved there</Link>. You can then import that content back to **Hygraph** by following these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9a8jasi07w5f1hupm1i" caption="Import translation" />

1. Navigate to the **Lokalise** section of the **Content editor**. Use the checkboxes to select the entries that you want to import translations for, then click on the `Import Translation` link at the top of the form.
2. A pop-up will display, where you need to select the language or languages of the content being imported. Select the necessary checkboxes, and click on the `Import translation` button. The translation status will change to `Imported` as a result.

**The following fields are supported to be imported from Lokalise:**

- Single-line text
- Multi-line text
- Markdown
- Richtext
- Slug

Import is also supported for Basic and Modular Components, but only for the supported field types.

<Alert theme="info">

Please note that the status <b>Done</b> means that all translations on <b>Lokalise</b> have been finished and that the content is ready to be imported.

</Alert>

### Translation statuses

The **Lokalise** app view of the **Content editor** contains a form that allows you to view the localization status of your content as well as to export and import translations in bulk.

![Lokalise secton in App view](/images/docs/integrations/lokalise/lokalise-appview.png)

Your **Locale status** refers to the default language in your project. The language will be indicated next to the column title, i.e. `Locale status (en)`.

Your **Global status** refers to all the languages that were submitted for translation.

| Status      | Description                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| Missing     | Indicates that an entry has never been sent to Lokalise.                                                         |
| In progress | Indicates that an entry has been submitted for translation.                                                      |
| Done        | Indicates that all translations have been finished in Lokalise, marked as reviewed, and imported.                |
| Changed     | Indicates that an entry has been edited after it was sent to Lokalise.                                           |
| Imported    | Indicates that one or more translations - but not all - have been finished in Lokalise, and imported to Hygraph. |

### View translations

1. Navigate to the **content editor**, and select the view of the model you included **Lokalise** in.
2. Edit an entry that you imported a translation for by clicking on the pencil icon. The content will display at the center of the screen.
3. You will find the `Localizations` section in the right sidebar. You have the following options:
   1. Click on the `+` icon to add a translation.
   2. Click on the trash icon to delete a translation.
   3. Click on the eye icon to view a translation in the editor.

![View translations](/images/docs/integrations/lokalise/lokalize-add-visualize.png)

## Troubleshooting

If the **Content Editor** displays the message `This model has no localized fields` under localizations in the sidebar, while the **Schema Editor** has localizations configured, go to **Project settings > Locales**. There, make sure your project has at least two languages configured.

![Locales in project settings](/images/docs/integrations/lokalise/lokalise-settings-locales.png)

If you have only one language configured there, select another language for localizations using the `Display name` dropdown, then click on `Add`.

<Alert theme="warning">

Please note that free plans can have a maximum of 2 locales.

</Alert>

## Resources

- <Link href="https://docs.lokalise.com/en/" target="_blank">Lokalise documentation</Link>.


---
# Connect your Hygraph project to Mux

Source: https://hygraph.com/docs/integrations/connect-mux

**Mux** is a platform dedicated to solving all video-related problems that software teams may have, including live-streaming, video chat, on-demand video catalog, etc.

## What you can do with the Hygraph-Mux integration

With this app you can quickly launch video features, customize player experience, and monitor video streaming performance.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **Mux** account. If you don't have one yet, you can get one <Link href="https://dashboard.mux.com/signup" target="_blank">here</Link>.
- You must have your **Mux** `Access token` and `Token secret`. You can create these keys by navigating to **Settings > Access Tokens** in your **Mux** account.
- You must have access to your `Signing key ID` and the `Base64-encoded Private Key` to be able to use `Signed URL` option for your videos. You can create these keys by navigating to **Settings > Signing keys** in your **Mux** account.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Mux app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-mux-app" target="_blank">here</Link> to install the Mux App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/wUA0Br0XRYS5tHkrQHsm" caption="Install Mux app" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click on `Install app`.
2. The permissions pop-up will display. Click on `Authorize app` to continue. You will be redirected to the configuration screen.
3. Fill in the `Access token` and the `Token secret`. You can create these keys by navigating to **Settings > Access Tokens** in your **Mux** account.

   <Alert theme="warning">
     You can only access this information in Mux if you have permissions to do
     so.
   </Alert>

   If you don't enter these credentials correctly, the UI will let you know that the provided token & secret pair is not able to create an upload:

   ![Mux - Provided token and secret pair is not able to create an upload](/images/docs/integrations/mux/wrong-token-secret-pair.png)

4. To be able to use the `Signed URL` option for your videos, you need to also fill in the `Signing key ID` and the `Base64 private key` fields. You can create these keys by navigating to **Settings > Signing keys** in your **Mux** account.
5. Use the radio buttons to select a `Default URL policy`. `Public` is selected by default, but you can also select `Signed`. This option determines the default global setting for your Mux videos. You will have the option to overwrite this later on for each upload.

   <Alert theme="warning">

   If you don't complete the `Signing key ID` and the `Base64 private key` fields, the `Signed` option will be disabled. A tooltip indicating this displays when you scroll over `Default URL policy`.

   ![Mux - Signed URL disabled](/images/docs/integrations/mux/signed-url-disabled.png)

   </Alert>

6. Click on the `Save` button. A pop-up notification on the lower right corner of the screen will indicate that the changes have been saved.

<Alert title="Pro Tip" theme="info">

While you select the default URL policy for your project during app installation, please take into account that a user can overwrite this settings while creating content, as the video selection screen [allows them to set a URL policy for each new upload](/docs/integrations/connect-mux#upload-a-new-video).

</Alert>

### Removing signed URL keys

If signed URL keys are removed from your project's app configuration after installation, videos that were previously uploaded using a signed URL will fail to load on the selection screen.

![Mux - Video not loading due to signed URL keys removal](/images/docs/integrations/mux/video-not-loading.png)

If added to a content entry, they will also fail to load in the content editor, and you will get a network error when attempting to play them. If you scroll over the thumbnail, a tooltip will display indicating that the token is invalid.

![Mux - Video not loading in the content editor](/images/docs/integrations/mux/video-not-loading-contenteditor.png)

## Add the Mux field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/0HeWu8D3RlOeC3r5q9td" caption="Add Mux video field" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **Mux field** to and click on it.
3. Select the **Mux field** from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your **Mux field**: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
6. Click on the `Add` button.

## Use Mux in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/3oF4iKCT8qpPOB3yLZCf" caption="Use Mux in content entry" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Mux field** for.
3. Click on the `+ Add entry` button or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Mux field** section of the screen and click on `Add or upload video via Mux`. This opens a new screen where you can select an existing video or upload a new one. Check out our [Mux selection screen](/docs/integrations/connect-mux#mux-selection-screen) document section to learn more about this step.
5. After selecting the video(s) you want and returning to the content entry, the selected video(s) will display on the list.
   ![Mux - Videos in content entry](/images/docs/integrations/mux/videos-content-entry.png)
6. You can optionally use the six dots icon to drag and drop the videos to organize them in the order you want.
7. Now that the video has been added to the entry, you can click on `Save` or `Save & Publish`, as needed.

Once added to the content entry, each video in the Mux field has a three dots context menu with the following options:

![Mux - Context menu](/images/docs/integrations/mux/mux-context-menu.png)

- `Copy link to video:` Click on this option to copy the link to the video.
- `Remove:` Click on this option to remove the video from the list. If you want to remove all videos from the list, simply click on the `Clear` link located at the top right of the list.

**If your Mux field is configured to allow only one video**, the `Replace video` button will display once you've added a video. Click on it to replace your video selection.

![Mux - Replace video](/images/docs/integrations/mux/mux-replace-video.png)

## Mux selection screen

This screen pops up when you click on `Add or upload video via Mux` while creating or editing a content entry. Here you can select existing videos or upload new ones.

![Mux selection screen](/images/docs/integrations/mux/mux-selection-screen.png)

1. You can use the filters at the top of the table to quickly find the videos you're looking for. You can filter by `Asset ID` or `Livestream ID`.
2. If the Mux field in your project allows selecting multiple values, a selection checkbox will display next to each video. If the field only allows a single value, a selection icon will display instead, and the video will be added to the content entry when you click on that icon.
3. You can use the pagination tools at the bottom of the screen to navigate the table.
4. A button at the lower left corner of the screen allows you to select whether new uploads should be public or have a signed URL. The default state of this button depends on your `Default URL policy` selection during [installation](/docs/integrations/connect-mux#install-the-mux-app). Videos with a signed URL display a lock icon at the upper right corner of the thumbnail.

![Mux video with signed URL](/images/docs/integrations/mux/mux-video-signed-url.png) 5. There are three action buttons at the lower right corner of the screen:

- `Cancel`: Click on this button to close the selection screen without adding a video to the content entry.
- `Upload`: Click on this button to upload a new video. URL Policy will reflect your `Signed URL` selection in point `4` of this list. The videos are uploaded to your Mux account and display on the selection screen, where you have the option to select them and add them to a content entry.
- `Add selected videos`: Click on this button after selecting the videos you want to include in the content entry. A number between brackets to the right of the button indicates how many videos you selected. Selecting at least one video enables this button.

### Select an existing video

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/UXjt7nePRNSYkju116kO" caption="Select video from Mux" />

1. Click on `Add or upload video via Mux` in the **Mux field** section of the content editor to open the selection screen.
2. Here you have two options depending on field configuration:
   - **The field allows multiple values:** Find the videos you want to add and select them using the checkboxes.
   - **The field does not allow multiple values:** Find the video you want to add and click on the `Add` icon, located at the top right of each video thumbnail.
3. The final step also depends on field configuration:
   - **The field allows multiple values:** Click on the `Add selected videos` button to return to the content editor. The selected videos will display in your content entry as a result.
   - **The field does not allow multiple values:** You will be redirected to the content editor automatically after clicking on the selection icon in the previous step. You will find your selected video in the Mux field section of your content entry.

You can repeat this process to add more videos if field configuration allows multiple entries, or you can click on `Replace video` if only one video is allowed and you want to change your selection.

### Upload a new video

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/HcYrZo68TEaYtSlwwc6A" caption="Upload video to Mux" />

1. Click on `Add or upload video via Mux` in the **Mux field** section of the content editor to open the selection screen.
2. Use the lock icon at the bottom left of the screen to select if the video should be `Public` or use a `Signed URL`. This option overwrites the global setting selected during installation, which is shown here as the default option.

<Alert title="Pro Tip" theme="info">

The signed URL option requires that you create a signing key in Mux, used to secure requests. You can create these keys in **Settings > Signing Keys** in your Mux account. Check out <Link href="https://docs.mux.com/api-reference#system/tag/signing-keys" target="_blank">Mux's API documentation for Signing Keys</Link> if you want to know more.

</Alert>

3. Click on `Upload` at the lower right corner of the screen to upload new videos.
4. A selection screen will pop up, where you can select one or multiple videos at the same time. Simply select them with a mouse click then click on `Upload`.

   After uploading, the video displays on the selection screen along with the rest of your assets. Depending on how large your video file is, the thumbnail may take a few seconds to load.

5. To select this video and add it to your content entry, click on the selection icon or checkbox located at the upper right corner of the video thumbnail.

## Resources

- <Link href="https://docs.mux.com/" target="_blank">Mux documentation</Link>
- <Link href="https://docs.mux.com/api-reference#system/tag/signing-keys" target="_blank">Mux Signing keys documentation</Link>

&nbsp;


---
# Connect your Hygraph project to Netlify

Source: https://hygraph.com/docs/integrations/connect-netlify

The integration lets you update your static deployments via a button in the Hygraph content view. Handled differently than by webhooks, the only configuration needed is connecting your Hygraph project to your Netlify site/app and selecting which content entries can trigger a rebuild via the UI.

This integration allows you to install a button in the Hygraph sidebar of a content model for manual redeploys, alongside a visual indicator of deployment status.

### What you can do with the Hygraph-Netlify integration

- Trigger Netlify builds within your content view with a single click.
- View the status of your Netlify build without leaving the Hygraph UI.
- Specify which content models display the button in the sidebar, giving you more control over how builds are triggered when there are changes to your content.

### Prerequisites to use this integration

- When using this integration, you should already have a static site deployed in an active Netlify project. Don’t have one? Set up a <Link href="https://app.netlify.com/signup" target="_blank">free Netlify account</Link> or <Link href="https://www.netlify.com/pricing" target="_blank">learn about other plans</Link>!
- You should have an existing Hygraph project. Sign up for a <Link href="https://app.hygraph.com" target="_blank">free Hygraph developer account</Link>.
- You should configure your Netlify site to support continuous deployment.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## How it works

### Step 1) Install the Netlify app

<Link href="https://app.hygraph.com/apps/netlify/new" target="_blank">Click here</Link> to install Netlify app on Hygraph.

![](/images/docs/integrations/netlify/connect-netlify-01.png)

### Step 2) Select a project

Select which project you want to install the app in, then click **Add App**.

![](/images/docs/integrations/netlify/connect-netlify-02.png)

### Step 3) Connect Hygraph to Netlify

Click on **Connect to Netlify** to setup the connection with Hygraph.

![](/images/docs/integrations/netlify/connect-netlify-03.png)

### Step 4) Authorize the Netlify app

Click on **Authorize** to allow the app to perform actions on your behalf. After authorizing the app, you can close the tab and go back to Hygraph homepage.

![](/images/docs/integrations/netlify/connect-netlify-04.png)

### Step 5) Set up your website

In the dropdown, select your website on Netlify, add a **Display Name**, then click on **Save**.

![](/images/docs/integrations/netlify/connect-netlify-05.png)

### Step 6) Adding Netlify deploy button to models

Now, go to the **Schema** editor and select the model you want to add Netlify deploy button.

![](/images/docs/integrations/netlify/connect-netlify-06.png)

### Step 7) Adding Netlify sidebar widget

Click on the **Sidebar** tab. Then, click on **Netlify Deployment** to add the widget to the sidebar.

![](/images/docs/integrations/netlify/connect-netlify-07.png)

### Step 8) Customizing sidebar widget

You can change the widget **Display Name** and **Description** if you want. Otherwise, click on **Create**.

![](/images/docs/integrations/netlify/connect-netlify-08.png)

### Step 9) Reordering widget

Click and hold the six-dotted handle and drag the widget to the position you want to display in the sidebar.

![](/images/docs/integrations/netlify/connect-netlify-09.png)

## How to trigger a deploy on Netlify

### Step 1) Go to content view

Go to the content editing section. You can do that by clicking on the left-side navigation or the "Go to content editing" link in the top-right corner.

![](/images/docs/integrations/netlify/connect-netlify-10.png)

### Step 2) Go to model content view

Under the **views** section, select the model you added the widget in the previous step. Then, click on the Edit button to open an existing entry. You can also create a new Entry.

![](/images/docs/integrations/netlify/connect-netlify-11.png)

### Step 3) Triggering deploy

On the sidebar, you should see Netlify deploy button. Click on it to trigger a new build.

![](/images/docs/integrations/netlify/connect-netlify-12.png)


---
# Connect your Hygraph project to Plasmic

Source: https://hygraph.com/docs/integrations/connect-plasmic

**Plasmic** is visual no-code page builder and CMS for any website or codebase, which you can use your existing code components with.

## What you can do with the Hygraph-Plasmic integration

Integrate Hygraph with Plasmic to create websites using a no-code visual page builder where the content is populated by Hygraph.

This allows non-technical, non-developer users to build pages, without the need to rely on developer teams.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **Plasmic** account. If you don't have one yet, you can get one <Link href="https://studio.plasmic.app/signup" target="_blank">here</Link>.
- You must have a **Plasmic** project with a workspace set up. The <Link href="https://docs.plasmic.app/learn/no-code-quickstart/" target="_blank">Plasmic no-code quickstart</Link> contains detailed information on how to do this.

## Connect your projects

### Step 1: Add a PAT to your Hygraph project

![Add a PAT to your Hygraph project](/images/docs/integrations/plasmic/add-pat.png)

1. In your Hygraph project, go to `Settings > Access > API access > Permanent Auth Token`.
2. In the Permanent Auth Token section, click on `+Add token` to add a new token. Type in a `Token name` for it and, optionally, add a `Description`. Use the radio buttons to select a `Default stage for content delivery`.
3. Click on `Add & configure permissions`.
4. Look for the token you've just added in the **Permanent Auth Tokens** list. Click on the three dots context menu, and select the `Edit` option.
5. Initialize the default permissions for the **Content API** and the **Management API** by clicking on the purple `Initialize default permissions` button in each of the two sections.

<Alert title="Pro Tip" theme="info">

[Check out our document on permanent auth tokens](/docs/api-reference/basics/authorization#permanent-auth-tokens) to learn more about this.

</Alert>

### Step 2: Install Hygraph in your Plasmic project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/mXMo7LkdTMuaR98NNtmZ" caption="Install Hygraph in Plasmic" />

1. Click on the blue `+` button located at the top left corner of your Plasmic project.
2. Look for `Hygraph` using the search field.
3. Click on the Hygraph package to install it.
4. Click on `Go to settings` on the `Project Settings` popup that displays on the upper right corner of the screen to access the installed package, which contains the `API URL` and the `Auth token`.

<Alert title="Pro Tip" theme="info">

If you miss the popup, you can find your Project Settings in the left side menu of your Plasmic project dashboard. You can see exactly where at the end of the previous video.

</Alert>

### Step 3: Connect your projects

![Add your Hygraph PAT and API IRL](/images/docs/integrations/plasmic/connect-apps.png)

1. In your project settings, select `GraphCMS Credentials Provider`.
   <Alert theme="info">
     Our company has recently changed its name to Hygraph. Our name in Plasmic
     will soon be updated, but for now please note that it shows our old name.
   </Alert>
2. Replace the `API URL` value in Plasmic with the `Content API` endpoint from your Hygraph project. You will find it by navigating to `Settings > Access > API access > Endpoints > Content API` in your Hygraph project.
3. Replace the `Auth Token` value in Plasmic with the value for the PAT you created in Hygraph for [Step 1 of this tutorial](/docs/integrations/connect-plasmic#step-1-add-a-pat-to-your-hygraph-project). To copy the value, go to `Settings > Access > API access > Permanent Auth Token` in your Hygraph project and click on the copy icon.

Your projects are now connected.

## Use Plasmic with Hygraph

Now that your projects are connected, you will need to add a **Fetcher** and then a **Field** inside it.

To add them:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/mzGvFQXzSSCPNrwqtoPi" caption="Add Hygraph content fields in Plasmic" />

1. Click on the blue `+` icon at the top left corner of the screen, and type "GraphCMS" in the search field.
2. Drag and drop the **GraphCMS Fetcher** element from the search results, into the place in your project where you want to have it.
3. Set a query for the **Fetcher** element by clicking on `unset` next to `Query` on the right sidebar.
4. Type in your query in the playground, and run it to test that it works. Once you've tested it, click on `Save`.
5. Click on the **GraphCMS Fetcher** element on the template to display its settings on the right sidebar.
6. Click on `unset` next to `Field` to open the field selection screen.
7. A popup will show you all the fields that you set up in the query. Click on one to select it, then click on `Save`.

The selected content should be fetched and displayed on your frontend preview.

## Resources

- <Link href="https://docs.plasmic.app/learn/" target="_blank">Plasmic documentation</Link>
- <Link href="https://docs.plasmic.app/learn/no-code-quickstart/" target="_blank">Plasmic no-code quickstart</Link>
- <Link href="https://www.youtube.com/watch?v=PACZDi-dIv0" target="_blank">Visually build Hygraph pages with Plasmic</Link>


---
# Connect your Hygraph project to Scaleflex Filerobot

Source: https://hygraph.com/docs/integrations/connect-scaleflex-filerobot

**Scaleflex Filerobot** allows you to gain control of your digital assets. This agnostic software - compatible with all applications and operative systems - can help teams to store, process, share, and accelerate images, videos, and static content on web or mobile applications.

## What you can do with the Hygraph-Scaleflex Filerobot integration

With this app you can upload, store, edit, manage, optimize, enrich and automate your media right within your Hygraph UI.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **Scaleflex Filerobot** account. If you don't have one yet, you can request a demo <Link href="https://www.scaleflex.com/request-a-demo" target="_blank">here</Link>.
- You must have a **Scaleflex Filerobot** project `Container ID`. You can find it in the top right corner of your Filerobot dashboard, by your username.
- You must have a **Scaleflex Filerobot** project `Security template`. You can create it in your Scaleflex Filerobot project by navigating to **Settings > Development > Security templates** and clicking on `+ Add template`.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Scaleflex Filerobot app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-scaleflex-filerobot-app" target="_blank">here</Link> to install the Scaleflex Filerobot App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/LzaZRWQpQS8McY62lTPQ" caption="Install Scaleflex Filerobot app" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click on `Install app`.
2. The permissions pop-up will display. Click on `Authorize app` to continue. You will be redirected to the configuration screen.
3. Fill in the `Container ID` field with the ID your copied from your Filerobot dashboard, and the `Security template key` with the `Security template` that you copied from your Filerobot Development settings. You can find these keys in your Scaleflex Filerobot project by following the steps we described in our [prerequisites section](/docs/integrations/connect-scaleflex-filerobot#prerequisites-to-use-this-integration).
4. Click on `Save config settings` to finalize the installation process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

## Add the Filerobot field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/2DnA7QLqRaix65egavzg" caption="Add Filerobot asset field" />

1. Navigate to the **Schema** builder.
2. Select the model that you want to add the **Filerobot field** to and click on it.
3. Select the **Filerobot asset picker** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your Filerobot field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the `Field options` section.
6. Click on the `Add` button.

## Use Scaleflex Filerobot in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/c17aLX7FRjW2ODkmPTpO" caption="Use Filerobot in Hygraph" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Filerobot field** for.
3. Click on the `+ Add entry` button or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **Filerobot** section of the screen and click on `Add Scaleflex asset`. This opens a new screen where you can select an existing asset or upload a new one.
5. Select the asset(s) you want, then click on `Export`. You will have the option to add the assets as is or transform them:
   - `As original`: This option is available for all assets. Adds them to the content entry as is.
   - `Transformation`: This option is only available for image assets. It lets you modify the image format, quality, size, and even crop part of it.
6. After selecting the asset(s) you want and returning to the content entry, your selection will display on the list.
   ![Filerobot - Images in content entry](/images/docs/integrations/scaleflex-filerobot/images-content-entry.png)
   You can optionally use the six dots icon to drag and drop the assets to organize them in the order you want.
7. Finally, click on `Save` or `Save & Publish`, as needed.

<Alert theme="info" title="Pro Tip">

- If you did not configure your Filerobot field to allow multiple vales, you won't be able to export a folder into your content entries. The system will let you know that you cannot export a folder to a single asset field.
- Exporting folders is not yet supported for multi-select fields.

</Alert>

## Resources

- <Link href="https://www.npmjs.com/package/@filerobot/readme" target="_blank">Filerobot documentation</Link>


---
# Connect your Hygraph project to Shopify

Source: https://hygraph.com/docs/integrations/connect-shopify

**Shopify** is a SaaS provider for merchants running online businesses. The company's platform includes online store creation, search engine optimization, hosting, marketing, payment, fulfillment, and security for small to enterprise sized businesses.

## What you can do with the Hygraph-Shopify integration

With this app you can continue to use Shopify as your preferred headless commerce solution for products and eCommerce assets. By installing the Shopify app, you can bring your Shopify products into Hygraph projects with the rest of your content.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have a **Shopify** account. If you don't have one yet, you can get one <Link href="https://www.shopify.com/" target="_blank">here</Link>.
- You must have created a **storefront** in your Shopify account. <Link href="https://help.shopify.com/en/manual/intro-to-shopify/initial-setup/setup-getting-started" target="_blank">Here</Link> is some information on how to get started.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Shopify app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-shopify-app" target="_blank">here</Link> to install the Shopify App on **Hygraph**, then follow these steps:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/PrbCNNzATM6HCsmXd8ti" caption="Install Shopify app" />

1. In the dropdown, select which project you want to install the app in, then click on the `Add App` button. You should be redirected to the **Configure Shopify** section of your Hygraph project.
2. Fill in the `Storefront token` and the `Store domain`. You will find a link next to each of these fields with details on how to get this information.
3. Click on the `Save` button. A pop-up notification in the lower right corner of the screen will indicate that the changes have been saved.

## Add the Shopify product field to your model

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/2L6A8PsSFecZ79KlWir7" caption="Add Shopify product field" />

1. Navigate to the **Schema** builder.
2. Select the model that you would like to add the **Shopify product picker** field to and click on it.
3. Select the **Shopify product picker** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`. This screen allows you to control different properties of your **Shopify product picker** field: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
5. Click on the `Create` button.

## Use Shopify in your Hygraph project

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/dQ5wGh7nTjiyFlk27Zww" caption="Use Shopify in Hygraph" />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **Shopify product picker** field for.
3. Click on the `+ Create entry` button or, alternatively, edit an existing entry.
4. Locate the **Shopify product picker** section of the screen and click on `Select product from Shopify`. As a result, a new screen will display, showing the products available in your Shopify store.
5. Select the product you wish to add to the entry, then click on the `Select product` button.
6. Now that the product has been added to the entry, you can click on `Save` or `Save & Publish`, as needed.

## Resources

- <Link href="https://help.shopify.com/en/manual/intro-to-shopify" target="_blank">Shopify documentation</Link>


---
# Connect your Hygraph project to Smartling

Source: https://hygraph.com/docs/integrations/connect-smartling

**Smartling** is a cloud-based language translation and content localization tool that offers translation services as well as AI powered translations.

## What you can do with the Hygraph-Smartling integration

- Teams can simplify their workflows between **Smartling** and **Hygraph** by submitting & importing content.
- Teams can easily manage multiple locales for their digital products through a dedicated interface within **Hygraph**.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project).
- You must have a **Smartling** account. If you don't have one, you can <Link href="https://www.smartling.com/meeting-request/" target="_blank">book a meeting with their team</Link>.
- You must have a Smartling project. Check out <Link href="https://help.smartling.com/hc/en-us" target="_blank">Smartling Help Center</Link> to find out more about how Smartling works.
- You must create a Smartling project and have the following information at hand:
  - `User ID:` Generate this by clicking on `Account settings`, located on the upper right corner of the screen - by your user menu - then select the `API` option. Find the **Account tokens** section of the screen and click on the `Create Token` button. Finally, assign a name to your token and click on `Create`. Your `User ID` is the `Token Name`. Copy this information, as you won't be able to access it afterwards.
  - `User Secret:` Generate this by clicking on `Account settings`, located on the upper right corner of the screen - by your user menu - then select the `API` option. Find the **Account tokens** section of the screen and click on the `Create Token` button. Finally, assign a name to your token and click on `Create`. Your `User Secret` is the `Token Secret`. Copy this information, as you won't be able to access it afterwards.
  - `Project ID:` Find this by clicking on `Account settings`, located on the upper right corner of the screen - by your user menu - then select the `API` option. Find the **Project tokens** section of the screen. You can copy the `Project ID` of an existing project, or generate a new one by clicking on `Create Token`.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the Smartling app

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-smartling-app" target="_blank">here</Link> to install the **Smartling** app on **Hygraph**, then follow these steps:

<VideoEmbed videoId="XeJMFeRcFKc" />

1. In the dropdown, select which project you want to install the app in, then click on the `Install app` button, then authorize permissions.
2. Fill in the `User ID`, `User secret`, `Project ID`. This information can be found in your **Smartling** account. The **Hygraph** UI provides a link with information on how to get them at the top of the screen. We also provided information on this in the [Prerequisites](/docs/integrations/connect-smartling#prerequisites-to-use-this-integration) section of this document.
3. Select at least one translatable model to use **Smartling** in. This information can be edited later by going to the **Apps** section of your Hygraph project, and editing the app details.
4. Map the locales by using the dropdown menu to select a Smartling locale to match your Hygraph locale. This information might take a few seconds to load after entering a `Project ID`.
5. Click `Save`.

<Alert title="Pro Tip" theme="info">

The Smartling app creates a dedicated custom app view in the content editor. This means that you can start using it right away, without having to make any schema modifications.

</Alert>

## Use Smartling in your Hygraph project

The Smartling app does not need to be manually added to models from your project schema. Instead, after installation, you will find the Smartling app view in the **Content editor**, under **App views**.

As you create content for the models you selected during installation, this content will display here. From here, you will be able to [submit](/docs/integrations/connect-smartling#submit-translation) translations to **Smartling**, and then [import](/docs/integrations/connect-smartling#import-translation) those translations back into **Hygraph**.

<Alert theme="warning">

Please note that only the content created using the <b>Models</b> that you selected during the <b>Smartling installation process</b> will display on this list.

You can edit this from your <b>Hygraph project</b> by navigating to `Apps > Smartling`, clicking `Edit` on the app card, and then using the checkboxes to select the models you want.

</Alert>

Finally, after installing the app, you will be able to [view the translated content](/docs/integrations/connect-smartling#view-translations) normally by accessing the **Content editor**.

Take into account that only localizable fields can be submitted to Smartling. So the fields must be set as localized fields when added to the model.

![Localize field checkbox](/images/docs/integrations/smartling/localize-field.png)

You will find the `Localize field` checkbox in the **Field options** section of the field details screen. To check if a field is localized, you can open the project **Schema** and and look at the field card, or edit the field to view its details.

### Submit translation

<VideoEmbed videoId="XeJMFeRcFKc" start={63} />

1. Navigate to the **content editor**.
2. Select **Smartling** under the **App view** section of the screen.
3. Use the checkboxes to select the content that you want to submit from the list, and send it to **Smartling** by clicking on the `Submit for translation` link at the top of the table. Content that has not been submitted has the `Missing` status.
4. A pop-up will display, where you need to select the job and locales to submit.
    - **New job**
      - **Name new job:** Type in a name for the new job.
      - **Enter job description:** Optional. You can add a description for the new job here.
      - **Select job due date:** Click the calendar icon to select a due date for the new job, then click `Ok`.
    - **Existing job**
      - **Select existing:** Use the dropdown menu to select an existing job. Selecting pre-existing jobs does not change the authorization status.
    - **Locales:** Use the checkboxes to select the locales you want to submit for translation.
    - **Pre-authorize:** You can select this checkbox to pre-authorize the translations. Pre-authorized translations do not need to be authorized from your Smartling project after submitting. This checkbox displays only for new jobs.
5. Click `Submit` to send the translation to Smartling. Its status will change to `In progress`, and you will be able to find the content ready to translate in your **Smartling** account.

If the content is exported successfully, a green toast will indicate this. If it fails, a red toast will indicate that the process was unsuccessful. You can check out the <Link href="https://help.smartling.com/hc/en-us/articles/1260805481410-Error-Codes" target="_blank">Smartling documentation</Link> to look into the possible cause of errors.

#### Supported fields

**The following fields are supported to be submitted to Smartling:**

- Single-line text
- Multi-line text
- Markdown
- Rich text
- Slug

We also support translation submissions for basic and modular Components, **but only for the supported field types**.

### Import translation

After [submitting](/docs/integrations/connect-smartling#submit-translation) content to **Smartling**, it will be ready for translation there. Once translated, you can then import that content back to **Hygraph** by following these steps:

<VideoEmbed videoId="XeJMFeRcFKc" start={137} />

1. Navigate to the **Smartling** app view in the **Content editor**. Use the checkboxes to select the entries that you want to import translations for, then click `Import translations` at the top of the table.
2. The sync popup will display:
    - **Locales:** Use the checkboxes to select the locales you want to import translations for.
3. Click `Import translations`.

- If you successfully import all entries, you will get a green toast indicating so.
- If the import is partially successful, you will get a yellow toast indicating how many entries were imported successfully and how many failed.
- If the import fails, you will get a red toast indicating so.

### Search and filters

![Search and filters](/images/docs/integrations/smartling/search-and-filters.png)

- You can search for specific entries by typing in their  `ID` or `Title` in the search fields.
- You can also use the dropdowns to apply filters to show entries for specific models, locales, or locale statuses.
- The `Outdated` dropdown lets you filter by `All`, `Only outdated`, and `Only up to date` entries.
- The `Items per page` dropdown lets you select how many entries per page the table should display.

### Translation statuses

The **Smartling** app view in the **Content editor** contains a form that allows you to view the localization status of your content as well as to submit and import translations in bulk.

![Smartling section in App view](/images/docs/integrations/smartling/translation-statuses.png)

Your **Locale status** refers to the default language in your project. You can see the language next to the `Title`, for instance `Title (en)`.

Your **Global status** refers to all the languages that were submitted for translation.

| Status      | Description                                                                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing     | Indicates that an entry has never been submitted to Smartling.                                                                                                                    |
| In progress | Indicates that an entry has been submitted for translation.                                                                                                                       |
| Done        | Indicates that the translation has been finished in Smartling and has moved onto the next step in the workflow. This means that the translation can be imported back into Hygraph |

<Alert theme="info" title="Pro Tip">

You can click `Refresh all` at the top-right of the table to refresh the status of all localizations on the table.

</Alert>

### View translations

To view translations in the content form:

1. Navigate to the **content editor**, and select the view of the model you configured **Smartling** for.
2. Edit an entry that you imported a translation for by clicking on the pencil icon. The content will display at the center of the screen.
3. You will find the `Localizations` section in the right sidebar. You have the following options:
   1. Click on the `+` icon to add a translation.
   2. Click on the trash icon to delete a translation.
   3. Click on the eye icon to visualize a translation in the editor.

![View translations](/images/docs/integrations/smartling/smartling-view.png)

## Troubleshooting

### No localized fields

If the **Content Editor** displays the message `This model has no localized fields` under localizations in the sidebar, while the **Schema** has localizations configured, go to **Project settings > Locales** and make sure your project has at least two languages configured.

![Locales in project settings](/images/docs/integrations/smartling/settings-locales.png)

If you have only one language configured there, select another language for localizations using the `Display name` dropdown, then click on `Add`.

<Alert theme="warning">

Please note that free plans can have a maximum of 2 locales.

</Alert>

### Errors

Error messages in Hygraph will provide a Smartling error code and description. Check out the <Link href="https://help.smartling.com/hc/en-us/articles/1260805481410-Error-Codes" target="_blank">Smartling documentation</Link> to learn about those errors and how to solve them.

## Resources

- [Smartling app changelog](/docs/integrations/changelog-smartling)
- <Link href="https://help.smartling.com/hc/en-us" target="_blank">Smartling Help Center</Link>


---
# Connect your Hygraph project to TinyMCE

Source: https://hygraph.com/docs/integrations/connect-tinymce

**TinyMCE** is an open-source online rich-text editor. It converts HTML textarea fields, or other designated HTML elements, into editor instances.

## What you can do with the Hygraph-TinyMCE integration

With this app you can quickly generate HTML, creating and editing content in a format similar to using a word processor.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](/docs/getting-started/fundamentals/quickstart#create-a-model).

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## Install the TinyMCE app

Click <Link href="https://app.hygraph.com/apps/tiny-mce/new" target="_blank">here</Link> to install the TinyMCE App on **Hygraph**, then follow these steps:

<VideoEmbed videoId="l7HmHn7Hakw" />

1. Use the dropdowns to select which project and environment you want to install the app in, then click on `Install app`.
2. Click on `Authorize app` to authorize app permissions and move on to the configuration screen.
3. Customize your toolbar options by selecting the checkboxes you want regarding formatting, alignment, indentation, history, styles, elements, headings, formats and miscellanea. You can come back and edit this selection later if you need to.
4. Click `Save Config Settings`.

## Add the TinyMCE field to your model

<VideoEmbed videoId="l7HmHn7Hakw" start={88} />

1. Navigate to the **Schema** builder.
2. Select the model where you want to add the **TinyMCE** field.
3. Select the **TinyMCE** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your **TinyMCE field**: you can allow multiple values, or you can localize the field, by selecting the checkboxes under the `Field options` section of the screen.
6. Click `Add` to save.

## Use TinyMCE in your Hygraph project

<VideoEmbed videoId="l7HmHn7Hakw" start={125} />

1. Navigate to the **Content** editor.
2. Select the view that you configured the **TinyMCE** field for.
3. Click `+ Add entry` or, alternatively, edit an existing entry by clicking on it.
4. Locate the **TinyMCE** field section of the screen and you can start writing content in it right away. If any of the options you need are not visible, simply go back to the **App Configuration** screen and use the checkboxes to select it.
5. Once you finish working on your content entry, click `Save` or `Save & Publish` depending on your workflow.

## Resources

- <Link href="https://www.tiny.cloud/docs/tinymce/latest/" target="_blank">TinyMCE documentation</Link>


---
# Connect your Hygraph project to Vercel

Source: https://hygraph.com/docs/integrations/connect-vercel

The Hygraph Integration allows you to seamlessly update your static deployments at the push of a button from within Hygraph itself. Not to be confused with triggered builds via webhooks, this integration allows you to install a button in the Hygraph sidebar of a content model for manual redeploys.

## What you can do with the Hygraph-Vercel integration

- Trigger Vercel builds from within your content view with a single click.
- Specify which content models display the button in the sidebar, giving you more control over how builds are triggered when there are changes to your content.

## Prerequisites to use this integration

- When using this integration, you should already have a static site deployed in an active Vercel project. Don't have one? Set up a **<Link href="https://vercel.com/signup" target="_blank">free Vercel account</Link>** or **<Link href="https://vercel.com/pricing" target="_blank">learn about other plans</Link>**!
- You should have an existing Hygraph project. Sign up for a **<Link href="https://app.hygraph.com/" target="_blank">free Hygraph developer account</Link>**.
- Your Vercel site should be configured to support continuous deployment.

<Alert theme="warning">

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## How to install the Vercel app

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/Zlo08d3TAm6iNt7t1ADA" caption="Install Vercel app" />

To install apps on Hygraph, you should go to our <Link href="https://hygraph.com/marketplace" target="_blank">marketplace</Link>. Under the **Hosting & Deployment** category, you will find the <Link href="https://hygraph.com/marketplace/apps/hygraph-vercel-app" target="_blank">Vercel app</Link>. Click on it to open the page.

1. Click on the **Install Vercel for Hygraph** button to start the installation flow.

2. In the dropdown, select which project you want to install the app in, then click on the **Add App** button. You should be redirected to your Hygraph project homepage.

3. Click on the **Connect to Vercel** button to connect Hygraph to the project hosted on Vercel. You should be redirected to the Vercel website, where you can see information about the app and authorize the installation. Click on the **Add Integration** button to authorize the app.

4. In the dropdown, select the **Vercel Account** to add the integration to, then click on the **Continue** button. You will be redirected back to the Hygraph dashboard.

5. Now, select the Vercel **project** in the dropdown, enter the GitHub repository **Branch name** and the **Display Name**. Finally, click on the **Save** button.

Now that the app is installed, the next step is to add the **Vercel build button** to the sidebar of to one or more of your project's models, so that you can trigger builds from the content editor.

## How to add the build button to the sidebar

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/Zlo08d3TAm6iNt7t1ADA" caption="Add Vercel build button to sidebar" />

1. On the left side navigation, go to the **Schema** editor.

2. Under the **Models** section, click on the model you want to add the **Vercel build** button to.

3. Click on the **Sidebar** tab.

4. Under **Sidebar Widgets**, click on the **Deploy to Vercel** widget to add it to the sidebar.

   <Alert theme="info">

   If you can't see the widget in the sidebar, you should do a hard refresh of the page by hitting <code>Ctrl + R</code> (Windows/Linux) or <code>Cmd + R</code> (macOS). Then, you should see it.

   </Alert>

5. In the **Add Widget** pop-up, **Display Name** and **Description** fields will be pre-filled. You can edit them if you want. Otherwise, just click on the **Create** button to add it to the model sidebar.

6. Finally, you can drag and drop the widget by clicking on the six dots icon to reorder the sidebar widgets if you want.

Now, let's learn how to trigger builds from the content editor.

## How to trigger a build

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/SpzUVAOQXXUWffWj6ZUQ" caption="Trigger a Vercel build" />

1. Click on the **Go to content editing** link at the top right of the Schema editor. Alternatively, you can also click on the **Content** icon, in the left side navigation.
2. Click on the model you added the sidebar widget to.
3. Click on the **Edit** button of an existing entry. Or click on the **Create Entry** button.
4. Finally, click on the **Start Building** button, located in the sidebar. Once you do that, the button state changes and the build will start on Vercel. Under the button, you should see the last date a build has been triggered.

## Using our starter projects with Vercel

Follow these steps:

![Hygraph starter - Documentation project used as example](/images/docs/integrations/vercel/vercel-docs-starter.png)

1. Create a new project by selecting one of the starters in <Link href="https://app.hygraph.com/" target="_blank">Hygraph</Link>.

2. Click on the **Create project** button. You will be redirected to your Hygraph project homepage.

3. Access the **starter's GitHub repository** on a different tab, scroll down to visualize the **README** document contents, and click on the **Deploy** button.

   <Alert theme="info">

   You can also alternatively skip steps 1 and 2, and clone the project directly from the GitHub repository mentioned in this step. The <b>Clone project</b> button is next to the <b>Deploy</b> button.

   </Alert>

4. Create a GitHub repository for your project, and then provide the values for the required environment variables. [Click here](/docs/integrations/connect-vercel#environment-variables) for information on how to configure your project easily.

![Configure your Vercel Project](/images/docs/integrations/vercel/vercel-configure-project.png)

6. Click on the **Deploy** button.

### Environment variables

Use this information to configure your Vercel project.

| VARIABLE NAME                      | WHERE TO FIND IT                                                                                                                                                  |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HYGRAPH_ENDPOINT                   | Located in the **API Access** section of your Hygraph **Project settings**, under **Endpoints**.                                                                  |
| HYGRAPH_DEV_TOKEN                  | Located in the **API Access** section of your Hygraph **Project settings**, under **Permanent Auth Tokens**.                                                      |
| HYGRAPH_MUTATION_TOKEN             | Located in the **API Access** section of your Hygraph **Project settings**, under **Permanent Auth Tokens**.                                                      |
| HYGRAPH_QUERY_TOKEN                | Located in the **API Access** section of your Hygraph **Project settings**, under **Permanent Auth Tokens**.                                                      |
| HYGRAPH_PROD_TOKEN                 | Located in the **API Access** section of your Hygraph **Project settings**, under **Permanent Auth Tokens**.                                                      |
| HYGRAPH_TOKEN                      | Located in the **API Access** section of your Hygraph **Project settings**, under **Permanent Auth Tokens**.                                                      |
| NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | This is not located in Hygraph. You will find this information in your **third party configuration**.                                                             |
| NEXTAUTH_SECRET                    | This is not located in Hygraph. You will find this information in your **third party configuration**.                                                             |
| NEXTAUTH_URL                       | This is not located in Hygraph. You will find this information in your **third party configuration**.                                                             |
| PREVIEW_SECRET                     | Find it in your Hygraph custom configuration. You will find this in the **Schema builder**, in the **Sidebar** tab of the model that contains the preview widget. |
| STRIPE_SECRET_KEY                  | This is not located in Hygraph. You will find this information in your **third party configuration**.                                                             |
| STRIPE_WEBHOOK_SIGNING_SECRET      | This is not located in Hygraph. You will find this information in your **third party configuration**.                                                             |

<Alert theme="warning">

Please note that not all starters use the same variables, so you may only need to use part of the list.

</Alert>


---
# Integrations

Source: https://hygraph.com/docs/integrations/index

## Overview

Apps are a core aspect to Hygraph's extensibility. They extend the capabilities of your Hygraph project by bringing in functionality from tools and services you're accustomed to using within your workflows.

In this documentation section, you'll find step-by-step guides that will help you integrate Hygraph with a number of apps, as well as additional information on how to use those apps in your Hygraph project.

## Installing apps

You can install an app by selecting it from our <Link href="https://hygraph.com/marketplace/apps" target="_blank">Marketplace</Link>, where you can navigate the apps page to find what you're looking for, or filter them by category.

![Apps in Hygraph Marketplace](/images/docs/integrations/apps-hygraph-marketplace.png)

Once you find the app that you want to integrate your Hygraph project with, you can click on its card to display the app details page. The details page contains everything you need to get started, such as basic app information and links to our step-by-step integration guides.

Simply click on the purple installation button to start.

In general, the installation process starts by prompting you to select which project and environment you want to install the app in, then authorizing the necessary permissions. The last step involves providing some information in your app's configuration page to ensure your project is linked to it. The information required there depends on the app, as different apps have different prerequisites. Each app integration guide details what that information is, and how to find it in the app you're integrating. Please take a look at our [Section contents](/docs/integrations#section-contents) to learn about available apps.

## Modifying apps configuration

There are situations where you might want to change the information you initially provided in the configuration screen when you first installed an app. For instance, some apps require you to select models, asset types, or provide keys.

To edit this information, navigate to the `Apps` section of you Hygraph project, find the card of the app you need to edit information for, then click on the pencil icon.

![Edit app information](/images/docs/integrations/edit-app-information.png)

Clicking on the pencil icon opens the configuration page, where you can edit the information that you provided during the initial configuration.

## Uninstalling apps

To uninstall an app, navigate to the `Apps` section of you Hygraph project, and click on the `Uninstall app` icon.

![Uninstalling apps](/images/docs/integrations/unisntall-app.png)

To ensure that you don't accidentally delete an app, you will need to confirm that you want to do this by typing the name of the app in a confirmation popup, then clicking on the `Uninstall app` button.

## Apps in cloned environments

When you clone an environment, any installed apps are also copied. However, for security purposes, cloned apps will be in an "incomplete setup" state.

To fully activate the app, you must manually re-enter sensitive details like passwords or API keys.

Once the setup is complete, the app will function just as it did in the original environment.

## Section contents

This section offers a contents map to help you readily find what you're looking for.

### Digital assets management

| Document                                                                      | Contents                                                                                           |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Connect Aprimo](/docs/integrations/connect-aprimo)                           | Contains all the necessary information to integrate your Hygraph project with Aprimo.              |
| [Connect AWS S3](/docs/integrations/connect-aws-s3)                           | Contains all the necessary information to integrate your Hygraph project with AWS S3.              |
| [Connect Bynder](/docs/integrations/connect-bynder)                           | Contains all the necessary information to integrate your Hygraph project with Bynder.              |
| [Connect Cloudinary](/docs/integrations/connect-cloudinary)                   | Contains all the necessary information to integrate your Hygraph project with Cloudinary.          |
| [Connect Imgix](/docs/integrations/connect-imgix)                             | Contains all the necessary information to integrate your Hygraph project with Imgix.               |
| [Connect Mux](/docs/integrations/connect-mux)                                 | Contains all the necessary information to integrate your Hygraph project with Mux.                 |
| [Connect Scaleflex Filerobot](/docs/integrations/connect-scaleflex-filerobot) | Contains all the necessary information to integrate your Hygraph project with Scaleflex Filerobot. |

### Headless commerce & ecommerce

| Document                                                          | Contents                                                                                     |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Connect BigCommerce](/docs/integrations/connect-bigcommerce)     | Contains all the necessary information to integrate your Hygraph project with BigCommerce.   |
| [Connect commercetools](/docs/integrations/connect-commercetools) | Contains all the necessary information to integrate your Hygraph project with commercetools. |
| [Connect Shopify](/docs/integrations/connect-shopify)             | Contains all the necessary information to integrate your Hygraph project with Shopify.       |

### Hosting & deployment

| Document                                              | Contents                                                                               |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Connect Netlify](/docs/integrations/connect-netlify) | Contains all the necessary information to integrate your Hygraph project with Netlify. |
| [Connect Vercel](/docs/integrations/connect-vercel)   | Contains all the necessary information to integrate your Hygraph project with Vercel.  |

### Localization

| Document                                                          | Contents                                                                                     |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Connect Lokalise](/docs/integrations/connect-lokalise)           | Contains all the necessary information to integrate your Hygraph project with Lokalise.      |
| [Connect Crowdin](/docs/integrations/connect-crowdin)             | Contains all the necessary information to integrate your Hygraph project with Crowdin.       |
| [Connect DeepL](/docs/integrations/connect-deepl)             | Contains all the necessary information to integrate your Hygraph project with DeepL.       |
| [Connect EasyTranslate](/docs/integrations/connect-easytranslate) | Contains all the necessary information to integrate your Hygraph project with EasyTranslate. |
| [Connect Smartling](/docs/integrations/connect-smartling)         | Contains all the necessary information to integrate your Hygraph project with Smartling.     |

### Miscellaneous

| Document                                              | Contents                                                                               |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Connect Adminix](/docs/integrations/connect-adminix) | Contains all the necessary information to integrate your Hygraph project with Adminix. |
| [Connect Plasmic](/docs/integrations/connect-plasmic) | Contains all the necessary information to integrate your Hygraph project with Plasmic. |

### Product information management

| Document                                                                      | Contents                                                                                           |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Connect Akeneo](/docs/integrations/connect-akeneo)                           | Contains all the necessary information to integrate your Hygraph project with Akeneo.              |


---
# Image banner

Source: https://hygraph.com/docs/recipes/banners/banner-image

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build an image banner component containing a background image, a title, a subtitle for additional text, a button component and an enumeration for banner theme.

![Image banner component with fields](/images/docs/recipes/banners/banner-image-component-fields.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic models project.](/docs/recipes/banners/banner-image#clone-the-basic-models) If you're already familiar with model creation and only want to follow the parts of the tutorial related to the banners, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/banners/banner-image#clone-the-complete-cookbook) This is the way to go if you're curious about how the banners are made but don't want to follow the step-by-step creation process. This project contains the entire **Banners Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this banner to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

- **References:** 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.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/banners/banner-image#step-by-step-guide) Use this guide to create an image banner component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/banners/banner-image#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the banners right away, or you can clone the project that contains the entire **Banners cookbook** to compare the different banner configurations without having to clone multiple projects.

## Clone project

### Clone the basic models

We have prepared a project that contains only the basic models - Author, Shop, and Book - in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip model creation and [start from this step](/docs/recipes/banners/banner-image#create-a-link-component).

### Clone the complete cookbook

We have prepared a project that contains the entire **Banners cookbook**:

<Button
  href="https://app.hygraph.com/clone/720d86e74f47481ab3685aeb35090a11?name=Hygraph%20Recipes%20-%20Banners"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create banners, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Image banner"**.

This project also contains a demo model that includes all the banner components as basic components, as well as a modular component that you can use as a banner type selector.

## Step-by-step guide

Before we can build a component - in this case our image banner component - we sometimes need to create other schema elements that will later be added to those components as instances. 

In this guide, we will also be building nested components. When building nested components, you need to start building from the deepest level of nesting upwards, so you can have one component ready to nest it into the next one.

We will divide this process in steps to make it more manageable:

1. **Create the models:** We will create 3 sample models - Author, Book, and Shop - to use in our references.
2. **Create a link component:** We will build a link component that we can add to other components as a button or link element.
3. **Create an enumeration:** We will create an enumeration that will allow users to select a theme for their banners.
4. **Create the image banner component:** Finally, we'll combine the schema elements we created before to set up our image banner component.

### Create the models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/banners/banner-image#create-a-link-component) to continue the tutorial.

</Alert>

Since our image banner component will ultimately allow linking to external URLs as well as internal content, we need to create a set of models that we can reference later on.

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/banners/banner-author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/banners/banner-book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/banners/banner-shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create the link component.

### Create a link component

We are going to start by creating our first component. Our banners will need to have a link, and in this case we'll create a simple component for that.

<VideoEmbed videoId="_jF6woB572Y" />

We'll click `+Add` next to **Components** and we'll use the following information to create one:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Link  |
| API ID        | Link  |
| API ID Plural | Links |

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our link. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Link label                   |
| Settings    | API ID                         | linkLabel                    |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

We'll click `Add` to save.

We want our users to be able to add internal and external links, so we'll add a `Reference` field to relate internal content, and a `Slug` for external URLs.

We'll start with the external links. Let's add a `Slug` field, which will be our link URL. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. 

We'll use the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External link                                                                                                                                                                |
| Settings    | API ID                              | externalLink                                                                                                                                                                 |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

The way we configured the field validations to match a URL pattern will ensure that users will complete this field with a valid URL pattern, preventing errors. If their input does not match the expected pattern, the custom error message will inform them.

Next, we're going to ensure Editors can create internal links to content entries from the models that we created at the start of this tutorial. To achieve this, we'll add a `Reference` field. We'll find it on the **Add fields** right sidebar and use the following information:

| Tab                 | Field               | Input                                                        |
| ------------------- | ------------------- | ------------------------------------------------------------ |
| Define              | Reference type      | Select `Allow multiple models to be referenced (Union Type)` |
| Define              | Models to reference | Use the dropdown menu to select `Author`, `Book`, and `Shop` |
| Define              | Reference direction | Select `One-way reference`                                   |
| Configure reference | Display Name        | Internal link                                                |
| Configure reference | API ID              | internalLink                                                 |

We'll click `Add` to save.

Finally, we'll add a `Boolean` field that users can toggle to indicate if the link should open on a new tab. We'll find the `Boolean` field on the **Add fields** right sidebar and use the following information:

| Field        | Input   |
| ------------ | ------- |
| Display Name | New tab |
| API ID       | newTab  |

We'll click `Add` to save.

This is how you build a link component in Hygraph. You can add this component to different models in your schema. We will add this to our image banner later on.

![Link component](/images/docs/recipes/banners/components-link-done.png)

Next, we'll create our theme enumeration.

### Create an enumeration

The next step is to create the theme enumeration that we can later add to our image banner as a dropdown menu. 

<VideoEmbed videoId="QAinpqoVPDE" />

Let's navigate to our project schema and click `+Add` next to **Enumerations**.

We'll use the following information:

| Field        | Input |
| ------------ | ----- |
| Display Name | Theme |
| API ID       | Theme |

Next, we need to add enumeration values. These are the options we will get when using this later as a dropdown menu. For this example, we'll use two theme options - light and dark.

For every enumeration value, we need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

Finally, we'll click `Add enumeration` to save.

Now that our theme enumeration has been created, we can finally start building our image banner component.

### Create the image banner component

<VideoEmbed videoId="FlYwDTrSEyo" />

To start building our image banner component, we'll click `+Add` next to **Components** and use the following information to create one:

| Field         | Input        |
| ------------- | ------------ |
| Display Name  | Image banner |
| API ID        | ImageBanner  |
| API ID Plural | ImageBanners |

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with an `Asset picker` field, which will be our banner image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Background image |
| Settings | API ID       | backgroundImage  |

We'll click `Add` to save.

Next, we'll add a `Single line text` field, which will be our banner title. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Banner title                 |
| Settings    | API ID                         | bannerTitle                  |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |

We'll click `Add` to save.

We'll add another `Single line text` field, which will be our banner subtitle to add an additional line of text if we need it. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field        | Input           |
| -------- | ------------ | --------------- |
| Settings | Display Name | Banner subtitle |
| Settings | API ID       | bannerSubtitle  |

We'll click `Add` to save.

Earlier, we created a link component. We will now add it as a `Basic component` field so users will be able to add a links to their banners.

We'll find the `Basic component` field on the **Add fields** right sidebar, click on `Add` to add it, and use the following information:

| Tab      | Field                     | Input                                           |
| -------- | ------------------------- | ----------------------------------------------- |
| Settings | Display Name              | Banner button                                   |
| Settings | API ID                    | bannerButton                                    |
| Settings | Select allowed components | Use the dropdown to select the "Link" component |

We'll click `Add` to save.

Finally, we'll include the enumeration that we created earlier as an `enumeration` field using the following information:

| Tab      | Field        | Input                                 |
| -------- | ------------ | ------------------------------------- |
| Settings | Display Name | Banner theme                          |
| Settings | API ID       | bannerTheme                           |
| Settings | Enumeration  | Select "Theme" from the dropdown menu |

We'll click `Add` to save.

This is how you create an image banner for your Hygraph project!

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a banner using Hygraph. If you want to try out more banner configurations, we have a [banner slider](/docs/recipes/banners/banner-slider), a [references banner](/docs/recipes/banners/banner-references) and a [simple banner](/docs/recipes/banners/banner-simple) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# References banner

Source: https://hygraph.com/docs/recipes/banners/banner-references

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a banner model containing a title, a description and references.

It will allow you to create banners as content entries, and to reference content entries from different models in each banner.

![Simple banner component with fields](/images/docs/recipes/banners/references-banner-model.png)

Here is an example that shows how this banner could potentially look on your frontend:

![Example banner](/images/docs/recipes/banners/mock-banner-references.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic models project.](/docs/recipes/banners/banner-references#clone-the-basic-models) If you're already familiar with model creation and only want to follow the parts of the tutorial related to the banners, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/banners/banner-references#clone-the-complete-cookbook) This is the way to go if you're curious about how the banners are made but don't want to follow the step-by-step creation process. This project contains the entire **Banners Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this banner to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>


## Core concepts

In this guide, you'll work with components and basic component fields. Let's look into these concepts:

- **References:** 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.

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models and adding fields, reusable components, and sidebar widgets to them, as well as integrating remote sources and establishing relationships with other models.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/banners/banner-references#step-by-step-guide) Use this guide to create a references banner model that you can use to create different banners as content entries.
- [Path 2:](/docs/recipes/banners/banner-references#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the banners right away, or you can clone the project that contains the entire **Banners cookbook** to compare the different banner configurations without having to clone multiple projects.

## Clone project

### Clone the basic models

We have prepared a project that contains only the basic models - Author, Shop, and Book - in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip model creation and [start from this step](/docs/recipes/banners/banner-references#create-references-banner-model).

### Clone the complete cookbook

We have prepared a project that contains the entire **Banners cookbook**:

<Button
  href="https://app.hygraph.com/clone/720d86e74f47481ab3685aeb35090a11?name=Hygraph%20Recipes%20-%20Banners"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create banners, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"References banner"**.

This project also contains a demo model that includes all the banner components as basic components, as well as a modular component that you can use as a banner type selector.

## Step-by-step guide

In this guide, we will create a model as our banner. Before we can build our banner model, we need to create other models that we can then add as references to it.

We will divide this process in steps to make it more manageable:

1. **Create the referenced models:** We will create 3 sample models - Author, Book, and Shop - to use in our references.
2. **Create the banner model:** Finally, we will create our banner model and add reference fields to it.

### Create the basic models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/banners/banner-references#create-references-banner-model) to continue the tutorial.

</Alert>

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/banners/banner-author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/banners/banner-book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/banners/banner-shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create our references banner model.

### Create references banner model

<VideoEmbed videoId="CQUx_md7xd4" />

Our final model will be the **References banner** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input             |
| ------------- | ----------------- |
| Display Name  | References banner |
| API ID        | ReferencesBanner  |
| API ID Plural | ReferencesBanners |

We'll click `Add model` to save.

Our model has been created but it's empty. To create our banner model, we'll add the banner title, description, and reference fields.

Let's start with the banner title, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Banner title                 |
| Settings | API ID                        | bannerTitle                  |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our banner description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input              |
| -------- | ------------ | ------------------ |
| Settings | Display Name | Banner description |
| Settings | API ID       | bannerDescription  |

We'll click `Add` to save.

Finally, we'll add three reference fields, so our banners can reference content entries from the **Author**, **Book** and **Shop** models we created earlier.

We want to add them as one-way references, because we don't want to create reverse fields in these models. In this case, we just want to be able to link entries from them in the banner model.

<Alert theme="info" title ="Pro Tip">

The reverse field is a field that the system creates in the referenced model, so both models can reference each other.

Earlier, when we created the **Book** model, we added a two-way reference to it, because we wanted books to reference authors, but we also wanted authors to reference books.

In that case, we also allowed multiple books per author and multiple authors per book, because an author can have more than one book, and a book can have more than one author.

</Alert>

We'll link the Author model first. We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                 | Field                        | Input                                                 |
| ------------------- | ---------------------------- | ----------------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced`        |
| Define              | Models to reference          | Use the dropdown menu to select `Author`              |
| Define              | Reference direction          | Select `One-way reference`                            |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Author per References banner` |
| Configure reference | Display Name                 | Author                                                |
| Configure reference | API ID                       | author                                                |
| Configure reference | Description                  | You can add one or more showcased authors here        |

We'll click `Add` to save.

Next, we'll reference the **Book** model. We'll repeat the process using the following information:

| Tab                 | Field                        | Input                                               |
| ------------------- | ---------------------------- | --------------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced`      |
| Define              | Models to reference          | Use the dropdown menu to select `Book`              |
| Define              | Reference direction          | Select `One-way reference`                          |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Book per References banner` |
| Configure reference | Display Name                 | Book                                                |
| Configure reference | API ID                       | book                                                |
| Configure reference | Description                  | You can add one or more showcased books here        |

We'll click `Add` to save.

Finally, we'll reference the **Shop** model. We'll repeat the process using the following information:

| Tab                 | Field                        | Input                                               |
| ------------------- | ---------------------------- | --------------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced`      |
| Define              | Models to reference          | Use the dropdown menu to select `Shop`              |
| Define              | Reference direction          | Select `One-way reference`                          |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Shop per References banner` |
| Configure reference | Display Name                 | Shop                                                |
| Configure reference | API ID                       | shop                                                |
| Configure reference | Description                  | You can add one or more showcased shops here        |

We'll click `Add` to save.

This is how you build banner component in Hygraph that allows you to relate entries from other models in your schema. 

You can use this model to create banners with different referenced content as entries. 

You can also relate this banner model to other models in your project. [If you cloned the cookbook project](/docs/recipes/banners/banner-references#clone-project), you'll find the banner model included as a reference field in the **All banners** model.

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a banner using Hygraph. If you want to try out more banner configurations, we have a [simple banner](/docs/recipes/banners/banner-simple), a [banner slider](/docs/recipes/banners/banner-slider) and an [image banner](/docs/recipes/banners/banner-image) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Simple banner

Source: https://hygraph.com/docs/recipes/banners/banner-simple

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a simple banner component containing a title, a description, a component field for links, and an enumeration for theme selection.

It will let you add a both internal documents through references or external URLs.

![Simple banner component with fields](/images/docs/recipes/banners/simple-banner-component-fields.png)

Here is an example that shows how this banner could potentially look on your frontend:

![Example banner](/images/docs/recipes/banners/mock-banner-simple.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic models project.](/docs/recipes/banners/banner-simple#clone-the-basic-models) If you're already familiar with model creation and only want to follow the parts of the tutorial related to the banners, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/banners/banner-simple#clone-the-complete-cookbook) This is the way to go if you're curious about how the banners are made but don't want to follow the step-by-step creation process. This project contains the entire **Banners Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this banner to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, references, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/banners/banner-simple/#step-by-step-guide) Use this guide to create a simple banner component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/banners/banner-simple#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the banners right away, or you can clone the project that contains the entire **Banners cookbook** to compare the different banner configurations without having to clone multiple projects.

## Clone project

### Clone the basic models

We have prepared a project that contains only the basic models - Author, Shop, and Book - in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip model creation and [start from this step](/docs/recipes/banners/banner-simple#create-a-link-component).

### Clone the complete cookbook

We have prepared a project that contains the entire **Banners cookbook**:

<Button
  href="https://app.hygraph.com/clone/720d86e74f47481ab3685aeb35090a11?name=Hygraph%20Recipes%20-%20Banners"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create banners, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Simple banner"**.

This project also contains a demo model that includes all the banner components as basic components, as well as a modular component that you can use as a banner type selector.

## Step-by-step guide

Before we can build our simple banner component, we sometimes need to create other schema elements that will later be added to those components as instances. 

In this guide, we will also be building nested components. When building nested components, you need to start building from the deepest level of nesting upwards, so you can have one component ready to nest it into the next one.

We will divide this process in steps to make it more manageable:

1. **Create the models:** We will create 3 sample models - Author, Book, and Shop - to use in our references.
2. **Create a link component:** We will build a link component that we can add to other components as a button or link element.
3. **Create an enumeration:** We will create an enumeration that will allow users to select a theme for their banners.
4. **Create the simple banner component:** Finally, we'll combine the schema elements we created before to set up our simple banner component.

### Create the models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/banners/banner-simple#create-a-link-component) to continue the tutorial.

</Alert>

Since our simple banner component will ultimately allow linking to external URLs as well as internal content, we need to create a set of models that we can reference later on.

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/banners/banner-author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/banners/banner-book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/banners/banner-shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create the link component.

### Create a link component

We are going to start by creating our first component. Our banners will need to have a link, and in this case we'll create a simple component for that.

<VideoEmbed videoId="zjh6Rgi_GbY" />

We'll click `+Add` next to **Components** and we'll use the following information to create one:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Link  |
| API ID        | Link  |
| API ID Plural | Links |

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our link. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Link label                   |
| Settings    | API ID                         | linkLabel                    |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

We'll click `Add` to save.

We want our users to be able to add internal and external links, so we'll add a `Reference` field to relate internal content, and a `Slug` for external URLs.

We'll start with the external links. Let's add a `Slug` field, which will be our link URL. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. 

We'll use the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External link                                                                                                                                                                |
| Settings    | API ID                              | externalLink                                                                                                                                                                 |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

The way we configured the field validations to match a URL pattern will ensure that users will complete this field with a valid URL pattern, preventing errors. If their input does not match the expected pattern, the custom error message will inform them.

Next, we're going to ensure Editors can create internal links to content entries from the models that we created at the start of this tutorial. To achieve this, we'll add a `Reference` field. We'll find it on the **Add fields** right sidebar and use the following information:

| Tab                 | Field               | Input                                                        |
| ------------------- | ------------------- | ------------------------------------------------------------ |
| Define              | Reference type      | Select `Allow multiple models to be referenced (Union Type)` |
| Define              | Models to reference | Use the dropdown menu to select `Author`, `Book`, and `Shop` |
| Define              | Reference direction | Select `One-way reference`                                   |
| Configure reference | Display Name        | Internal link                                                |
| Configure reference | API ID              | internalLink                                                 |

We'll click `Add` to save.

Finally, we'll add a `Boolean` field that users can toggle to indicate if the link should open on a new tab. We'll find the `Boolean` field on the **Add fields** right sidebar and use the following information:

| Field        | Input   |
| ------------ | ------- |
| Display Name | New tab |
| API ID       | newTab  |

We'll click `Add` to save.

This is how you build a link component in Hygraph. You can add this component to different models in your schema. We will add this to our simple banner later on.

![Link component](/images/docs/recipes/banners/components-link-done.png)

Next, we'll create our theme enumeration.

### Create an enumeration

The next step is to create the theme enumeration that we can later add to our simple banner as a dropdown menu. 

<VideoEmbed videoId="tbKtE6SRdKk" />

Let's navigate to our project schema and click `+Add` next to **Enumerations**.

We'll use the following information:

| Field        | Input |
| ------------ | ----- |
| Display Name | Theme |
| API ID       | Theme |

Next, we need to add enumeration values. These are the options we will get when using this later as a dropdown menu. For this example, we'll use two theme options - light and dark.

For every enumeration value, we need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

Finally, we'll click `Add enumeration` to save.

Now that our theme enumeration has been created, we can finally start building our simple banner component.

### Create the simple banner component

<VideoEmbed videoId="u89p0CMrlXo" />

To start building our simple banner component, we'll click `+Add` next to **Components** and use the following information to create one:

| Field         | Input          |
| ------------- | -------------- |
| Display Name  | Simple banner  |
| API ID        | Simple banner  |
| API ID Plural | Simple banners |

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be our banner title. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Banner title                 |
| Settings    | API ID                         | bannerTitle                  |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our banner description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input              |
| -------- | ------------ | ------------------ |
| Settings | Display Name | Banner description |
| Settings | API ID       | bannerDescription  |

We'll click `Add` to save.

Earlier, we created a link component. We will now add it as a `Basic component` field so users will be able to add multiple links to their content entries.

We'll find the `Basic component` field on the **Add fields** right sidebar, click on `Add` to add it, and use the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Links                                           |
| Settings | API ID                           | links                                           |
| Settings | `Allow multiple values` checkbox | Select this checkbox                            |
| Settings | Select allowed components        | Use the dropdown to select the "Link" component |

We'll click `Add` to save.

The final step is to add an enumeration field so the users can select a banner theme. We'll select `Enumeration` on the **Add fields** right sidebar and use the following information:

| Tab      | Field        | Input                                 |
| -------- | ------------ | ------------------------------------- |
| Settings | Display Name | Banner theme                          |
| Settings | API ID       | bannerTheme                           |
| Settings | Enumeration  | Select "Theme" from the dropdown menu |

We'll click `Add` to save.

This is how you build a simple banner component in Hygraph. You can add this component to different models in your schema.

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a banner using Hygraph. If you want to try out more banner configurations, we have a [banner slider](/docs/recipes/banners/banner-slider), a [references banner](/docs/recipes/banners/banner-references) and an [image banner](/docs/recipes/banners/banner-image) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Banner slider

Source: https://hygraph.com/docs/recipes/banners/banner-slider

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a banner slider component using nested components for banner blocks and a number field as a timer.

![Banner component with fields](/images/docs/recipes/banners/banner-slider-component-fields.png)

Here is an example that shows how this banner could potentially look on your frontend:

![Example banner](/images/docs/recipes/banners/mock-banner-slider.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic models project.](/docs/recipes/banners/banner-slider#clone-the-basic-models) If you're already familiar with model creation and only want to follow the parts of the tutorial related to the banners, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/banners/banner-slider#clone-the-complete-cookbook) This is the way to go if you're curious about how the banners are made but don't want to follow the step-by-step creation process. This project contains the entire **Banners Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this banner to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with components, basic component fields, nested components and references. Let's look into these concepts:

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

- **References:** 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.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/banners/banner-slider#step-by-step-guide) Use this guide to create a banner slider component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/banners/banner-slider#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the banners right away, or you can clone the project that contains the entire **Banners cookbook** to compare the different banner configurations without having to clone multiple projects.

## Clone project

### Clone the basic models

We have prepared a project that contains only the basic models - Author, Shop, and Book - in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip model creation and [start from this step](/docs/recipes/banners/banner-slider#create-a-link-component).

### Clone the complete cookbook

We have prepared a project that contains the entire **Banners cookbook**:

<Button
  href="https://app.hygraph.com/clone/720d86e74f47481ab3685aeb35090a11?name=Hygraph%20Recipes%20-%20Banners"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create banners, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Banner slide"**.

This project also contains a demo model that includes all the banner components as basic components, as well as a modular component that you can use as a banner type selector.

## Step-by-step guide

Before we can build a component - in this case, our banner slider - we sometimes need to create other schema elements that will later be added to those components as instances. 

In this guide, we will also be building nested components. When building nested components, you need to start building from the deepest level of nesting upwards, so you can have one component ready to nest it into the next one.

We will divide this process in steps to make it more manageable:

1. **Create the models:** We will create 3 sample models - Author, Book, and Shop - to use in our references.
2. **Create a link component:** We will build a link component that we can add to other components as a button or link element.
3. **Create the banner block component:** We'll create a banner block component that will allow us to add several banners to each slider.
4. **Create the banner slider component:** Finally, we'll combine the schema elements we created before to set up our banner slider component.

### Create the models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/7ef10278f73d48f9a8769a5ebf57f4c1?name=Hygraph%20Recipes%20-%20Banners%20(Basic%20Models)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/banners/banner-slider#create-a-link-component) to continue the tutorial.

</Alert>

Since our banner slider component will ultimately allow linking to external URLs as well as internal content, we need to create a set of models that we can reference later on.

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/banners/banner-author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/banners/banner-book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/banners/banner-shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create the link component.

### Create a link component

We are going to start by creating our first component. Our banners will need to have a link, and in this case we'll create a simple component for that.

<VideoEmbed videoId="OCUBQO-nkME" />

We'll click `+Add` next to **Components** and we'll use the following information to create one:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Link  |
| API ID        | Link  |
| API ID Plural | Links |

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our link. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Link label                   |
| Settings    | API ID                         | linkLabel                    |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

We'll click `Add` to save.

We want our users to be able to add internal and external links, so we'll add a `Reference` field to relate internal content, and a `Slug` for external URLs.

We'll start with the external links. Let's add a `Slug` field, which will be our link URL. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it. 

We'll use the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External link                                                                                                                                                                |
| Settings    | API ID                              | externalLink                                                                                                                                                                 |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

The way we configured the field validations to match a URL pattern will ensure that users will complete this field with a valid URL pattern, preventing errors. If their input does not match the expected pattern, the custom error message will inform them.

Next, we're going to ensure Editors can create internal links to content entries from the models that we created at the start of this tutorial. To achieve this, we'll add a `Reference` field. We'll find it on the **Add fields** right sidebar and use the following information:

| Tab                 | Field               | Input                                                        |
| ------------------- | ------------------- | ------------------------------------------------------------ |
| Define              | Reference type      | Select `Allow multiple models to be referenced (Union Type)` |
| Define              | Models to reference | Use the dropdown menu to select `Author`, `Book`, and `Shop` |
| Define              | Reference direction | Select `One-way reference`                                   |
| Configure reference | Display Name        | Internal link                                                |
| Configure reference | API ID              | internalLink                                                 |

We'll click `Add` to save.

Finally, we'll add a `Boolean` field that users can toggle to indicate if the link should open on a new tab. We'll find the `Boolean` field on the **Add fields** right sidebar and use the following information:

| Field        | Input   |
| ------------ | ------- |
| Display Name | New tab |
| API ID       | newTab  |

We'll click `Add` to save.

This is how you build a link component in Hygraph. You can add this component to different models in your schema. We will add this to our banner slider later on.

![Link component](/images/docs/recipes/banners/components-link-done.png)

We can now move on to the next step, which is building our banner block component.

### Create the banner block component

<VideoEmbed videoId="ZiEeUCjLnvY" />

A banner slider contains several banners that pass by on a timer. We will create a banner block component that we can later add to our banner slider as a basic component field that allows multiple values. This way, users can add several banners to the slider.

<Alert theme="info" title="Pro Tip">

Components act like a template. This means that with this configuration, you will be able to add several banners to a slider when you use the components in a content entry, but you will need to add content to the template every time you use it.

If your workflow would instead benefit from having a set of banners with content that you can link to the banner slider component, you could create a **Banner block** model instead of a component, and add the same fields we will be adding to it in this guide.

If you do this, when the time comes to add it to the banner slider component, instead of adding it as a basic component field, you will need to add it as a **one-way reference that allows multiple banner blocks per banner slider**.

That configuration will allow you to relate the entries that you create using the banner block model to your banner slider during content creation.

</Alert>

Our banner block component will contain a title, a description, an image and the link component we created earlier.

To start building our banner block component, we'll click `+Add` next to **Components** and use the following information to create one:

| Field         | Input        |
| ------------- | ------------ |
| Display Name  | Banner block |
| API ID        | BannerBlock  |
| API ID Plural | BannerBlocks |

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be our banner block title. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Banner title                 |
| Settings    | API ID                         | bannerTitle                  |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our banner block description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input              |
| -------- | ------------ | ------------------ |
| Settings | Display Name | Banner description |
| Settings | API ID       | bannerDescription  |

We'll click `Add` to save.

Next, we'll add an `Asset picker` field, which will be our banner block image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Banner image |
| Settings | API ID       | bannerImage  |

We'll click `Add` to save.

Earlier, we created a link component. We will now add it as a `Basic component` field so users will be able to add multiple links to their banners.

We'll find the `Basic component` field on the **Add fields** right sidebar, click `Add` to add it, and use the following information:

| Tab      | Field                     | Input                                           |
| -------- | ------------------------- | ----------------------------------------------- |
| Settings | Display Name              | Banner link                                     |
| Settings | API ID                    | bannerLink                                      |
| Settings | Select allowed components | Use the dropdown to select the "Link" component |

We'll click `Add` to save.

We can now move on to the final step, which is building our banner slider component.

### Create the banner slider component

<VideoEmbed videoId="5itSy8G2zno" />

To start building our banner slider component, we'll click `+Add` next to **Components** and use the following information to create one:

| Field         | Input         |
| ------------- | ------------- |
| Display Name  | Banner slider |
| API ID        | BannerSlider  |
| API ID Plural | BannerSliders |

Click `Add component` to save. 

We can now start adding instances to this component.

We want our slider to have a timer, and we want that timer to provide only certain values to our editors. To achieve this, we will add a `Number` field and configure some validations as well as some advanced settings.

We'll add the `Number` field from the **Add fields** right sidebar using the following information:

| Tab         | Field                        | Input                                                                                                                                                                                                  |
| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Settings    | Display Name                 | Slider timer                                                                                                                                                                                           |
| Settings    | API ID                       | sliderTimer                                                                                                                                                                                            |
| Validations | `Limit input range` checkbox | Select this checkbox. We'll use the dropdown to select `Between`, and we'll set the first value to 5 and the second to 10. Under `Custom error message` we will write "Pick a number between 5 and 10" |
| Advanced    | `Set initial value` checkbox | Select this checkbox. We'll type in 5 as our initial value                                                                                                                                             |

We'll click `Add` to save.

Using this configuration, our number field will only allow values between 5 and 10, ensuring editors can only pick a value within that range for the timer. If editors use an incorrect value, the error message will give them instructions to fix it.

Finally, We've set the initial value to 5, which means the field will show a 5 as its default slider timer value, but will allow editors to change it, providing they use a value between 5 and 10.

Finally, we'll add a basic component field for our banner blocks using the following information:

| Tab      | Field                            | Input                                                   |
| -------- | -------------------------------- | ------------------------------------------------------- |
| Settings | Display Name                     | Banner blocks                                           |
| Settings | API ID                           | bannerBlocks                                            |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                    |
| Settings | Select allowed components        | Use the dropdown to select the "Banner block" component |

We'll click `Add` to save.

This is how you create a banner block components with a timer and different levels of nesting.

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a banner using Hygraph. If you want to try out more banner configurations, we have a [simple banner](/docs/recipes/banners/banner-simple), a [references banner](/docs/recipes/banners/banner-references) and an [image banner](/docs/recipes/banners/banner-image) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Banners overview

Source: https://hygraph.com/docs/recipes/banners/section-index

## Overview

In this section, you will find recipes that you can use to create **banners** using different field configurations.

| Recipe                                                        | Description                                                                                       |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Simple banner](/docs/recipes/banners/banner-simple/)         | Learn how to create a simple banner                                                               |
| [References banner](/docs/recipes/banners/banner-references/) | Learn how to create a banner model that allows you to easily reference content from other models  |
| [Banner slider](/docs/recipes/banners/banner-slider/)           | Learn how to create a banner slide where you can add multiple banners that will change on a timer |
| [Image banner](/docs/recipes/banners/banner-image/)           | Learn how to create an image banner with                                                          |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Banners cookbook

We have prepared a project that contains the entire **Banners cookbook**:

<Button
  href="https://app.hygraph.com/clone/720d86e74f47481ab3685aeb35090a11?name=Hygraph%20Recipes%20-%20Banners"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create banners, so you can compare the different banner configurations without having to clone multiple projects.

This project also contains a demo model that includes all the banner components as basic components, as well as a modular component that you can use as a banner type selector.


---
# Styled button link

Source: https://hygraph.com/docs/recipes/buttons/button-link-styled

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a button component that uses dropdown fields for style selection, and contains a toggle button to indicate if the link is external.

This is the type of button you want if the button component is meant to be used in different pages in your project which have different styling options available.

Here, by adding styling option dropdown menus for size and theme, you'll give Editors the possibility to style the buttons using the options you provide.

Dropdowns are great for this, because while they have options, it will only be within a limited selection that ensures the whole project has a cohesive look & feel.

![Styled Button](/images/docs/recipes/buttons/styled-button-component-fields.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/buttons/button-link-styled#clone-project) This is the way to go if you're curious about how the buttons are made but don't want to follow the step-by-step creation process. This project contains the entire **Buttons Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this button to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/buttons/button-link-styled/#step-by-step-guide) Use this guide to create a styled button component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/buttons/button-link-styled/#clone-project) Clone the project that contains the entire **Buttons cookbook** to compare the different button configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Buttons cookbook**:

<Button
  href="https://app.hygraph.com/clone/b6639ee932124165991e4be553f070b2?name=Hygraph%20Recipes%20-%20Buttons"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create buttons, so you can compare the different button configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Styled button link"**.

This project also contains a demo model that includes all the button components as basic components, as well as a modular component that you can use as a button type selector.

## Step-by-step guide

<VideoEmbed videoId="7rqIPg8O5bg" />

Before we can build components, we sometimes need to create other schema elements that will later be added to those components as instances.

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create the enumerations

We will start by creating the enumerations that we can later add to our components as dropdown menus for the button style options. 

We'll start with the "Theme" enumeration. We'll navigate to our project schema and click `+Add` next to **Enumerations**.

We'll use the following information:

| Field        | Input        |
| ------------ | ------------ |
| Display Name | Button theme |
| API ID       | ButtonTheme  |

Next, we need to add enumeration values. These are the options we will get when using this later as a dropdown menu. For this example, we'll use two theme options - light and dark.

For every enumeration value, we need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

Finally, we'll click `Add enumeration` to save.

Now that our button theme enumeration has been created, we'll do the same for our button size enumeration.

We'll use the following information to create the enumeration:

| Field        | Input       |
| ------------ | ----------- |
| Display Name | Button size |
| API ID       | ButtonSize  |

Next, we need to add the following enumeration values in the same way we added values to the previous enumeration:

| Display name | API ID |
| ------------ | ------ |
| Large        | large  |
| Medium       | medium |
| Small        | small  |

Finally, we'll click `Add enumeration` to save.

### 2. Create the component

Now that we've created the enumerations that we're going to use later, we can build our **styled button component**. To do this, we'll click `+Add` next to **Components**.

The first step is to create the component itself. We'll use the following information:

| Field         | Input              |
| ------------- | ------------------ |
| Display Name  | Styled button link |
| API ID        | StyledButtonLink   |
| API ID Plural | StyledButtonLinks  |

We'll click `Add component` to save. We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be our button label. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                        |
| ----------- | ----------------------------------- | ---------------------------- |
| Settings    | Display Name                        | Label                        |
| Settings    | API ID                              | label                        |
| Settings    | `Use as title field` checkbox       | Leave this checkbox selected |
| Validations | `Make this field required` checkbox | Select this checkbox         |

We'll click `Add` to save.

We'll add one more `Single line text` field where we can later add our URL as a string:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Link                 |
| Settings    | API ID                              | link                 |
| Validations | `Make this field required` checkbox | Select this checkbox |

We'll click `Add` to save.

We want to add a `Boolean` field that we can toggle to indicate whether the link is external. We'll use the following information:

| Tab      | Field        | Input       |
| -------- | ------------ | ----------- |
| Settings | Display Name | Is external |
| Settings | API ID       | isExternal  |

We'll click `Add` to save.

Next, we'll add an `Enumeration` field, which will be one of our dropdown menus. Once again, we'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab      | Field        | Input                                        |
| -------- | ------------ | -------------------------------------------- |
| Settings | Display Name | Theme                                        |
| Settings | API ID       | theme                                        |
| Settings | Enumeration  | Select "Button theme" from the dropdown menu |

We'll click `Add` to save.

Finally, we'll add one more `Enumeration` field, for the button size:

| Tab      | Field        | Input                                       |
| -------- | ------------ | ------------------------------------------- |
| Settings | Display Name | Size                                        |
| Settings | API ID       | size                                        |
| Settings | Enumeration  | Select "Button size" from the dropdown menu |

We'll click `Add` to save.

We've created a button component that contains a button label and a link, has a toggle to indicate whether the button link is external or not, and has two dropdown menus to let you select a button theme and size.

![Styled Button](/images/docs/recipes/buttons/styled-button-component-fields.png)

Since this is a component, you can reuse it throughout your project wherever it is needed, without having to recreate it every time!

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our button recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

- [Simple button:](/docs/recipes/buttons/button-simple/) Look into the simplest possible way to build a basic button component in Hygraph.
- [Socials button:](/docs/recipes/buttons/button-socials/) Learn how to build a simple component that results in an icon for your socials that links to them when you click on it.
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Simple button

Source: https://hygraph.com/docs/recipes/buttons/button-simple

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a simple button component containing only a label and a link.

This is the simplest button component that you can create using Hygraph. It will let you add a URL and text for your button.

![Simple button component with fields](/images/docs/recipes/buttons/simple-button-component-fields.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/buttons/button-simple#clone-project) This is the way to go if you're curious about how the buttons are made but don't want to follow the step-by-step creation process. This project contains the entire **Buttons Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this button to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with components and basic component fields. Let's look into these concepts:

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/buttons/button-simple/#step-by-step-guide) Use this guide to create a simple button component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/buttons/button-simple/#clone-project) Clone the project that contains the entire **Buttons cookbook** to compare the different button configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Buttons cookbook**:

<Button
  href="https://app.hygraph.com/clone/b6639ee932124165991e4be553f070b2?name=Hygraph%20Recipes%20-%20Buttons"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create buttons, so you can compare the different button configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Simple button"**.

This project also contains a demo model that includes all the button components as basic components, as well as a modular component that you can use as a button type selector.

## Step-by-step guide

<VideoEmbed videoId="2FVytN1Sy5s" />

To build our **simple button component**, let's navigate to the Schema of our Hygraph project and click `+Add` next to **Components**.

The first step is to create the component itself. We'll use the following information:

| Field         | Input         |
| ------------- | ------------- |
| Display Name  | Simple button |
| API ID        | SimpleButton  |
| API ID Plural | SimpleButtons |

We'll click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our button. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Field                         | Input                        |
| ----------------------------- | ---------------------------- |
| Display Name                  | Text                         |
| API ID                        | text                         |
| `Use as title field` checkbox | Leave this checkbox selected |
| `Localize field` checkbox     | Leave this checkbox selected |

We'll click `Add` to save.

Finally, let's add a `Slug` field, which will be our button URL. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | URL                                                                                                                                                                          |
| Settings    | API ID                              | url                                                                                                                                                                          |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

This is how you build a simple button component in Hygraph. You could add this component to different models in your schema.

![Simple button component with fields](/images/docs/recipes/buttons/simple-button-component-fields.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our button recipes.

Check out the next document section for that!

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is the simplest button component that you can create using Hygraph. If you want to try out something more complex, we have a [button with social links](/docs/recipes/buttons/button-socials/) and a [styled button](/docs/recipes/buttons/button-link-styled/) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Button with social links

Source: https://hygraph.com/docs/recipes/buttons/button-socials

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a button component for your socials. It contains a dropdown for selecting social network icons, and a string field to add a link.

You can add this button to your project wherever you need to include icons that will link to your social networks.

We've created this as a component that you can later add to a model in your project as a component field. If you configure this field to allow multiple values, it will let you add different social links to a content entry.

![Button component with social links](/images/docs/recipes/buttons/socials-button-component-fields.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/buttons/button-socials#clone-project) This is the way to go if you're curious about how the buttons are made but don't want to follow the step-by-step creation process. This project contains the entire **Buttons Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this button to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/buttons/button-socials/#step-by-step-guide) Use this guide to create a social links component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/buttons/button-socials/#clone-project) Clone the project that contains the entire **Buttons cookbook** to compare the different button configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Buttons cookbook**:

<Button
  href="https://app.hygraph.com/clone/b6639ee932124165991e4be553f070b2?name=Hygraph%20Recipes%20-%20Buttons"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create buttons, so you can compare the different button configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Social links"**.

This project also contains a demo model that includes all the button components as basic components, as well as a modular component that you can use as a button type selector.

## Step-by-step guide

<VideoEmbed videoId="pExUNlC-O3A" />

Before we can build components, we sometimes need to create other schema elements that will later be added to those components as instances.

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create an enumeration

We will start by creating an enumeration that we can later add to our components as a dropdown menu for the social icons. To do that, we'll navigate to our project schema and click `+Add` next to **Enumerations**.

We'll use the following information to create our enumeration:

| Field         | Input         |
| ------------- | ------------- |
| Display Name  | Social icons |
| API ID        | SocialIcons  |

Next, we need to add enumeration values. These are the options we will get when using this later as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID    |
| ------------ | --------- |
| Instagram    | instagram |
| Facebook     | facebook  |
| X (Twitter)  | xTwitter  |
| Reddit       | reddit    |

Finally, we'll click `Add enumeration` to save.

### 2. Create a component

Now that we've created the enumeration we're going to use later, we can build our **social links component**. To do this, we'll click `+Add` next to **Components**.

The first step is to create the component itself. We'll use the following information:

| Field         | Input       |
| ------------- | ----------- |
| Display Name  | Social Link |
| API ID        | SocialLink  |
| API ID Plural | SocialLinks |

We'll click `Add component` to save.

We can now start adding instances to this component.

Let's start with an `Enumeration` field, which will be our dropdown menu. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                        |
| ----------- | ----------------------------------- | -------------------------------------------- |
| Settings    | Display Name                        | Icon                                         |
| Settings    | API ID                              | icon                                         |
| Settings    | Enumeration                         | Select "Social icons" from the dropdown menu |
| Settings    | `Use as title field` checkbox       | Leave this checkbox selected                 |
| Validations | `Make this field required` checkbox | Select this checkbox                 |

We'll click `Add` to save.

With this configuration, we've ensured that our enumeration field will use the social icons enumeration we created earlier, and will also be a required field.

Finally, we will add a `Single line text` field, so we can later add our URL as a string. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                        |
| ----------- | ----------------------------------- | ---------------------------- |
| Settings    | Display Name                        | URL                          |
| Settings    | API ID                              | url                          |
| Settings    | `Use as title field` checkbox       | Leave this checkbox selected |
| Validations | `Make this field required` checkbox | Select this checkbox |

We'll click `Add` to save.

Our URL string field is also required, ensuring the social icons we select will have a link to match.

This is one way to build a social links button component in Hygraph. You can add this component to different models in your schema.

![Button component with social links](/images/docs/recipes/buttons/socials-button-component-fields.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our button recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

- [Simple button:](/docs/recipes/buttons/button-simple/) Look into the simplest possible way to build a basic button component in Hygraph.
- [Styled button:](/docs/recipes/buttons/button-link-styled/) Learn how to build a button component that uses dropdown fields for style selection, and contains a toggle button to indicate if the link is external.
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>


---
# Buttons overview

Source: https://hygraph.com/docs/recipes/buttons/section-index

## Overview

In this section, you will find recipes that you can use to create **buttons** using different field configurations.

| Recipe                                                            | Description                                                 |
| ----------------------------------------------------------------- | ----------------------------------------------------------- |
| [Simple button](/docs/recipes/buttons/button-simple/)             | Learn how to create a simple button                         |
| [Button with social links](/docs/recipes/buttons/button-socials/) | Learn how to create a to link your socials                  |
| [Styled button link](/docs/recipes/buttons/button-link-styled/)   | Learn how to create a link button that uses style dropdowns |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Buttons cookbook

We have prepared a project that contains the entire **Buttons cookbook**:

<Button
  href="https://app.hygraph.com/clone/b6639ee932124165991e4be553f070b2?name=Hygraph%20Recipes%20-%20Buttons"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create buttons, so you can compare the different button configurations without having to clone multiple projects.

This project also contains a demo model that includes all the button components as basic component fields, as well as a modular component field that you can use as a button type selector.

---
# Card grid with components

Source: https://hygraph.com/docs/recipes/card-grid/card-grid-components

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a card grid using nested components.

This card grid contains a number field so you can indicate how many columns the grid should have, a modular component that lets you select card types for your grid, and a dropdown menu to select the size of the gap between cards.

Here is an example that shows how this card grid could potentially look on your frontend:

![Example card grid](/images/docs/recipes/card-grid/mock-card-grid-components.png)

It is a good option when you have different card types but don't want your content entries to become very large and hard to manage. By adding all your card types to a modular component, you offer Editors the possibility to dynamically select which card type they need.

![Card grid with components](/images/docs/recipes/card-grid/cardgrid-components-fields.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/card-grid/card-grid-components#clone-project) This is the way to go if you're curious about how the card grids are made but don't want to follow the step-by-step creation process. This project contains the entire **Card Grid Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this card grid to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, components, basic component fields, modular component fields, and nested components. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Modular component field**: a modular component field can have two or more components attached to it. 

- **Nested components:** functionality that allows you to create components within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/card-grid/card-grid-components/#step-by-step-guide) Use this guide to create a card grid component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/card-grid/card-grid-components/#clone-project) Clone the project that contains the entire **Card Grid cookbook** to compare the different card grid configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Card Grid cookbook**:

<Button
  href="https://app.hygraph.com/clone/5f1ac5e413bd42839cc16cf31071f0a6?name=Hygraph%20Recipes%20-%20Card%20Grid"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>


This cookbook contains all the recipes we have so far to create card grids, so you can compare the different card grid configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Card Grid - Components"**.

This project also contains a demo model that includes all the card grid components in the cookbook as basic component fields, as well as a modular component field that you can use as a card grid type selector.

## Step-by-step guide

Before we can build components, we sometimes need to create other schema elements that will later be added to those components as instances.

We will divide this process in steps to make it more manageable:

1. **Create enumerations:** We will need to create three different enumerations to provide styling options.
2. **Create a component for links:** We will create a simple link component for one of the card types we will work on afterward.
3. **Create a component for buttons:** We will create a simple button component for one of the card types we will work on afterward.
4. **Create the card type components:** We will create two components with slightly different card designs. The aim is to have the possibility to select a card type for our grid later on.
5. **Create the card grid:** Finally, we'll combine all the elements we worked on before to generate a dynamic card grid with a modular component that allows card type selection.

### 1. Create the enumerations

We will start by creating the enumerations that we can later add to our components as dropdown menus that will let us select different style options for our cards and card grid. 

We'll start with the "Theme" enumeration. We'll navigate to our project schema and click `+Add` next to **Enumerations**.

We'll use the following information:

| Field        | Input |
| ------------ | ----- |
| Display Name | Theme |
| API ID       | Theme |

![Theme enumeration](/images/docs/recipes/card-grid/cardgrid-components-theme-enum.png)

Next, we need to add enumeration values. These are the options we will get when using this later as a dropdown menu.

For the sake of this example, we will use simple styling options: dark & light. Later on, we will add this enumeration to our buttons and cards.

For every enumeration value, we need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

![Theme enumeration values](/images/docs/recipes/card-grid/cardgrid-components-theme-enum-values.png)

We'll click `Add enumeration` to save.

Now that our theme enumeration has been created, we'll create another one for padding, so we can later use a dropdown to decide what type of padding our cards will have.

We'll use the following information to create the enumeration:

| Field        | Input   |
| ------------ | ------- |
| Display Name | Padding |
| API ID       | Padding |

Next, we need to add the following enumeration values in the same way we added values to the previous enumeration:

| Display name | API ID |
| ------------ | ------ |
| Large        | large  |
| Medium       | medium |
| Small        | small  |

![Padding enumeration values](/images/docs/recipes/card-grid/cardgrid-components-padding-enum-values.png)

We'll click `Add enumeration` to save.

We'll create one final enumeration that we will later use to select the type of gap between our cards on the grid. We'll use the following information:

| Field        | Input     |
| ------------ | --------- |
| Display Name | Cards gap |
| API ID       | CardsGap  |

Next, we need to add the following enumeration values:

| Display name | API ID |
| ------------ | ------ |
| Large        | large  |
| Medium       | medium |
| Small        | small  |

![Cards gap enumeration values](/images/docs/recipes/card-grid/cardgrid-components-gap-enum-values.png)

Finally, we'll click `Add enumeration` to save.

### 2. Create the link component

It is time to create our first component. Our cards will need to have a link, and in this case we'll create a simple component for that.

We'll click `+Add` next to **Components** and we'll use the following information to create one:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Link  |
| API ID        | Link  |
| API ID Plural | Links |

![Link component](/images/docs/recipes/card-grid/cardgrid-components-link.png)

Click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our link. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Link label                   |
| Settings    | API ID                         | linkLabel                    |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

![Link component - Label](/images/docs/recipes/card-grid/cardgrid-components-link-label.png)

We'll click `Add` to save.

Finally, let's add a `Slug` field, which will be our link URL. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | URL                                                                                                                                                                          |
| Settings    | API ID                              | url                                                                                                                                                                          |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Make field required` checkbox      | Select this checkbox                                                                                                                                                         |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Link component - URL](/images/docs/recipes/card-grid/cardgrid-components-link-url.png)

We'll click `Add` to save.

This is how you build a simple link component in Hygraph. You can add this component to different models in your schema. We will add this to our cards later on.

![Link component](/images/docs/recipes/card-grid/cardgrid-components-link-done.png)

### 3. Create the button component

One of the cards we will create later will use a button component. Let's create it!

We'll use the following information to create the component itself:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Button  |
| API ID        | Button  |
| API ID Plural | Buttons |

![Link component](/images/docs/recipes/card-grid/cardgrid-components-button.png)

We'll click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our button. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Button label                 |
| Settings    | API ID                         | buttonLabel                  |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

![Link component - Label](/images/docs/recipes/card-grid/cardgrid-components-button-label.png)

We'll click `Add` to save.

Let's also add a `Slug` field, which will be our link URL. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | URL                                                                                                                                                                          |
| Settings    | API ID                              | url                                                                                                                                                                          |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Make field required` checkbox      | Select this checkbox                                                                                                                                                         |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Link component - URL](/images/docs/recipes/card-grid/cardgrid-components-button-url.png)

We'll click `Add` to save.

Finally, we'll add an `Enumeration` field for the button themes, which will be one of our dropdown menus. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                                 |
| ----------- | ------------------------------ | ------------------------------------- |
| Settings    | Display Name                   | Theme                                 |
| Settings    | API ID                         | theme                                 |
| Settings    | Enumeration                    | Select "Theme" from the dropdown menu |
| Validations | `Make field required` checkbox | Select this checkbox                  |

![Link component - Theme](/images/docs/recipes/card-grid/cardgrid-components-button-theme.png)

We'll click `Add` to save.

Our button component should look like this:

![Link component - Theme](/images/docs/recipes/card-grid/cardgrid-components-button-done.png)

### 4. Create the card type components

We need to create cards so we can add them to our card grid. In this example, we will create two card types showing two typical card schema element combinations. Each card type is a component, which we will later on add to our grid.

To create the first card type, we'll click `+Add` next to **Components** and use the following information:


| Field         | Input       |
| ------------- | ----------- |
| Display Name  | Card type 1 |
| API ID        | CardType1   |
| API ID Plural | CardType1S  |

![Card Type 1 component](/images/docs/recipes/card-grid/cardgrid-components-card1.png)

We'll click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the title of our card. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Title                        |
| Settings    | API ID                         | title                        |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

![Card Type 1 component - Title](/images/docs/recipes/card-grid/cardgrid-components-card1-title.png)

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will be the body of our card. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input |
| -------- | ------------ | ----- |
| Settings | Display Name | Body  |
| Settings | API ID       | body  |

![Card Type 1 component - Body](/images/docs/recipes/card-grid/cardgrid-components-card1-body.png)

We'll click `Add` to save.

The next thing we want to add here is the link component we created earlier, so our card can contain a link.

We'll select the `Basic component` field from the right sidebar and use the following information to create it:

| Tab      | Field                            | Input                                                                                      |
| -------- | -------------------------------- | ------------------------------------------------------------------------------------------ |
| Settings | Display Name                     | Link                                                                                       |
| Settings | API ID                           | link                                                                                       |
| Settings | `Allow multiple values` checkbox | Select this checkbox. This will allow you to later on add more than one link to your card. |
| Settings | `Select component` dropdown menu | Select the **"Link"** component                                                            |

![Card Type 1 component - Nested Link component](/images/docs/recipes/card-grid/cardgrid-components-card1-nested-link.png)

We'll click `Add` to save.

Next, we'll add an `Enumeration` field, which will be one of our dropdown menus. Once again, we'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                                 |
| ----------- | ------------------------------ | ------------------------------------- |
| Settings    | Display Name                   | Theme                                 |
| Settings    | API ID                         | theme                                 |
| Settings    | Enumeration                    | Select "Theme" from the dropdown menu |
| Validations | `Make field required` checkbox | Select this checkbox                  |

![Card Type 1 component - Theme enumeration](/images/docs/recipes/card-grid/cardgrid-components-card1-theme-enum.png)

We'll click `Add` to save.

Finally, we'll add one more `Enumeration` field, for the padding options:

| Tab         | Field                          | Input                                   |
| ----------- | ------------------------------ | --------------------------------------- |
| Settings    | Display Name                   | Padding                                 |
| Settings    | API ID                         | padding                                 |
| Settings    | Enumeration                    | Select "Padding" from the dropdown menu |
| Validations | `Make field required` checkbox | Select this checkbox                    |

![Card Type 1 component - Padding enumeration](/images/docs/recipes/card-grid/cardgrid-components-card1-padding-enum.png)

We'll click `Add` to save.

Our "Card type 1" component should look like this:

![Card Type 1 component](/images/docs/recipes/card-grid/cardgrid-components-card1-fields.png)

We now have our first card type ready! It contains a title, a body, a link component, and two enumerations that will let us select theme and padding options.

Let's now create our second card type component. We'll start by clicking `+Add` next to **Components** and repeating the process using this information:

| Field         | Input       |
| ------------- | ----------- |
| Display Name  | Card type 2 |
| API ID        | CardType2   |
| API ID Plural | CardType2S  |

![Card Type 2 component](/images/docs/recipes/card-grid/cardgrid-components-card2.png)

We'll click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the title of our card. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                        |
| ----------- | ------------------------------ | ---------------------------- |
| Settings    | Display Name                   | Title                        |
| Settings    | API ID                         | title                        |
| Settings    | `Use as title field` checkbox  | Leave this checkbox selected |
| Validations | `Make field required` checkbox | Select this checkbox         |

![Card Type 2 component - Title](/images/docs/recipes/card-grid/cardgrid-components-card2-title.png)

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will be the body of our card. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab         | Field                          | Input                |
| ----------- | ------------------------------ | -------------------- |
| Settings    | Display Name                   | Body                 |
| Settings    | API ID                         | body                 |
| Validations | `Make field required` checkbox | Select this checkbox |

![Card Type 2 component - Body](/images/docs/recipes/card-grid/cardgrid-components-card2-body.png)

We'll click `Add` to save.

Next, we'll add an `Asset picker` field, so we can later add an image to our card. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input |
| -------- | ------------ | ----- |
| Settings | Display Name | Image |
| Settings | API ID       | image |

![Card Type 2 component - Image](/images/docs/recipes/card-grid/cardgrid-components-card2-image.png)

We'll click `Add` to save.

The next thing we want to add here is the button component we created earlier. We'll select the `Basic component` field from the right sidebar and use the following information to create it:

| Tab         | Field                            | Input                             |
| ----------- | -------------------------------- | --------------------------------- |
| Settings    | Display Name                     | Button                            |
| Settings    | API ID                           | button                            |
| Settings    | `Select component` dropdown menu | Select the **"Button"** component |
| Validations | `Make field required` checkbox   | Select this checkbox              |

![Card Type 2 component - Nested button component](/images/docs/recipes/card-grid/cardgrid-components-card2-nested-button.png)

We'll click `Add` to save.

Next, we'll add an `Enumeration` field, which will be one of our dropdown menus. Once again, we'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                                 |
| ----------- | ------------------------------ | ------------------------------------- |
| Settings    | Display Name                   | Theme                                 |
| Settings    | API ID                         | theme                                 |
| Settings    | Enumeration                    | Select "Theme" from the dropdown menu |
| Validations | `Make field required` checkbox | Select this checkbox                  |

![Card Type 2 component - Theme enumeration](/images/docs/recipes/card-grid/cardgrid-components-card2-theme-enum.png)

We'll click `Add` to save.

Finally, we'll add one more `Enumeration` field, for the padding options:

| Tab         | Field                          | Input                                   |
| ----------- | ------------------------------ | --------------------------------------- |
| Settings    | Display Name                   | Padding                                 |
| Settings    | API ID                         | padding                                 |
| Settings    | Enumeration                    | Select "Padding" from the dropdown menu |
| Validations | `Make field required` checkbox | Select this checkbox                    |

![Card Type 2 component - Padding enumeration](/images/docs/recipes/card-grid/cardgrid-components-card2-padding-enum.png)

We'll click `Add` to save.

Our "Card Type 2" component should look like this:

![Card Type 2 component](/images/docs/recipes/card-grid/cardgrid-components-card2-done.png)

We now have our second card type ready! It contains a title, a body, a button component, an asset picker to add images, and two enumerations that will let us select theme and padding options.

### 5. Create the card grid

At this point, we've created everything we need in order to start working on our card grid component. We'll create a new component using this information:

| Field         | Input                  |
| ------------- | ---------------------- |
| Display Name  | Card Grid - Components |
| API ID        | CardGridComponents     |
| API ID Plural | CardGridComponentss    |

![Card grid component](/images/docs/recipes/card-grid/cardgrid-components-creation.png)

We'll click `Add component` to save. 

We can now start adding instances to this component.

Let's start with a `Number` field, which we can later use to indicate the number of columns that our grid should have. 

We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                |
| ----------- | ------------------------------ | -------------------- |
| Settings    | Display Name                   | Columns              |
| Settings    | API ID                         | columns              |
| Validations | `Make field required` checkbox | Select this checkbox |

![Card grid component - Number of columns](/images/docs/recipes/card-grid/cardgrid-components-number.png)

We'll click `Add` to save. 

Earlier, we created two card types. We will now add them as part of a `Modular component` field so when we use the card grid component, we will be able to select which card type to use in it.

We'll find the `Modular component` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab      | Field                            | Input                                                                     |
| -------- | -------------------------------- | ------------------------------------------------------------------------- |
| Settings | Display Name                     | Card types                                                                |
| Settings | API ID                           | cardTypes                                                                 |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                                      |
| Settings | Select allowed components        | Use the dropdown to select the "Card type 1" and "Card type 2" components |

![Card grid component - Card type selector](/images/docs/recipes/card-grid/cardgrid-components-cardtypes.png)

We'll click `Add` to save.

<Alert theme="info">
In the case of this modular component field, we will allow multiple values because without that we'd only be able to add a single card to our grid.
</Alert>

The final step will be to add an `Enumeration` field so we can later select the gap size between cards. We'll use the following information to create it:

| Tab      | Field        | Input                                     |
| -------- | ------------ | ----------------------------------------- |
| Settings | Display Name | Cards gap                                 |
| Settings | API ID       | cardsGap                                  |
| Settings | Enumeration  | Select "Cards gap" from the dropdown menu |

![Card grid component - Gap size](/images/docs/recipes/card-grid/cardgrid-components-gap.png)

We'll click `Add` to save.

We've created a card grid component that contains several other components nested in it at different levels, as well as other schema elements.

![Card grid with components](/images/docs/recipes/card-grid/cardgrid-components-fields.png)

<Alert theme="info" title="Pro Tip">
This step-by-step guide is a good example of why it is important to plan our content schema. Our objective was to create a card grid component, but before we could create that we needed to create a lot of other elements that would be a part of it.
</Alert>

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our card grid recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

[Learn how to create a card grid component that adds content entries in your project as cards!](/docs/recipes/card-grid/card-grid-references/)
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>


---
# Card grid with references

Source: https://hygraph.com/docs/recipes/card-grid/card-grid-references

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a card grid component that uses reference fields to relate content to an entry.

This card grid contains a number field so you can indicate how many columns the grid should have, a reference field that lets you relate content entries in your project as cards, and dropdown menus to select the size of the gap between cards and the theme.

Here is an example that shows how this card grid could potentially look on your frontend:

![Example card grid](/images/docs/recipes/card-grid/mock-card-grid-references.png)

It is a good option when you need to show content entries in your project as cards. A good example of this would be a card grid showing related entries, such as products.

![Card grid with references](/images/docs/recipes/card-grid/cardgrid-references-fields.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/card-grid/card-grid-references#clone-project) This is the way to go if you're curious about how the card grids are made but don't want to follow the step-by-step creation process. This project contains the entire **Card Grid Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this card grid to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

- **Enumerations:** An enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/card-grid/card-grid-references/#step-by-step-guide) Use this guide to create a card grid component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/card-grid/card-grid-references/#clone-project) Clone the project that contains the entire **Card Grid cookbook** to compare the different card grid configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Card Grid cookbook**:

<Button
  href="https://app.hygraph.com/clone/5f1ac5e413bd42839cc16cf31071f0a6?name=Hygraph%20Recipes%20-%20Card%20Grid"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create card grids, so you can compare the different card grid configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Card Grid - References"**.

This project also contains a demo model that includes all the card grid components in the cookbook as basic component fields, as well as a modular component field that you can use as a card grid type selector.

## Step-by-step guide

Before we can build components, we sometimes need to create other schema elements that will later be added to those components as instances. We will divide this process in steps to make it more manageable:

1. **Create the enumerations:** We will need to create enumerations so that we can later on use dropdown menus to select different styling options.
2. **Create models:** We will create three models so that we can select them as referenceable by the grid.
3. **Create the card grid:** Finally, we'll combine all the elements we worked on before to our card grid.

### 1. Create the enumerations

We will start by creating an enumeration that we can later add to our card grid component as a dropdown menu to select the gap size between our cards on the grid.

We'll navigate to our project schema,click `+Add` next to **Enumerations**, and use the following information to create our enumeration:

| Field        | Input     |
| ------------ | --------- |
| Display Name | Cards gap |
| API ID       | CardsGap  |

We'll click `Add enumeration` to save.

![Card grid with references - Cards gap enumeration](/images/docs/recipes/card-grid/cardgrid-references-gap-enum.png)

Next, we need to add enumeration values. For every enumeration value, we need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Large        | large  |
| Medium       | medium |
| Small        | small  |

Finally, we'll click `Add enumeration` to save.

![Card grid with references - Cards gap enumeration values](/images/docs/recipes/card-grid/cardgrid-references-gap-enum-values.png)

### 2. Create models

This card grid configuration will use references to link entries from models in our schema.

<Alert theme="info" title="Pro Tip">
In a real situation, you would use actual content models that you planned and built for your project, but for the sake of this example, we will simply create three empty content models so we can later on reference them.
</Alert>

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Product |
| API ID        | Product  |
| API ID Plural | Products |

![Card grid with references - Models](/images/docs/recipes/card-grid/cardgrid-references-models.png)

We'll click `Add model` to save.

Next, we'll create our second content model using the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Blog |
| API ID        | Blog  |
| API ID Plural | Blogs |

We'll click `Add Model` to save.

And one final time for our third model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Store |
| API ID        | Store  |
| API ID Plural | Stores |

We'll click `Add model` to save.

These are the three content models that we will include in our reference when we create the card grid.

### 3. Create the card grid

At this point, we've created everything we need in order to start working on our card grid component. 

We'll click `+Add` next to **Components** and use the following information:

| Field         | Input                  |
| ------------- | ---------------------- |
| Display Name  | Card Grid - References |
| API ID        | CardGridReferences     |
| API ID Plural | CardGridReferencess    |

![Card grid with references - Component](/images/docs/recipes/card-grid/cardgrid-references-component.png)

We'll click `Add component` to save. We can now start adding instances to this component.

Let's start with a `Number` field, which we can later use to indicate the number of columns on our grid.

We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                          | Input                |
| ----------- | ------------------------------ | -------------------- |
| Settings    | Display Name                   | Columns              |
| Settings    | API ID                         | columns              |
| Validations | `Make field required` checkbox | Select this checkbox |

![Card grid with references - Number of columns](/images/docs/recipes/card-grid/cardgrid-references-number.png)

We'll click `Add` to save. 

Earlier, we created three empty content models. We will now add them as part of a `Reference` field so when we use the card grid component, we will be able to relate content entries from those models. The entries we reference will be included as cards in our grid.

We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                        | Input                                                                     |
| ------------------- | ---------------------------- | ------------------------------------------------------------------------- |
| Define              | Reference type               | Select `Allow multiple models to be referenced (Union Type)`              |
| Define              | Models to reference          | Use the dropdown menu to select `Product`, `Blog` and `Store`        |
| Define              | Reference direction          | Select `One-way reference`                                                |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Product, Blog, Store per CardGridReferences` |
| Configure reference | Display Name                 | Cards                                                                     |
| Configure reference | API ID                       | cards                                                                     |

![Card grid with references - Reference field](/images/docs/recipes/card-grid/cardgrid-references-referencefield.png)

We'll click `Add` to save.

<Alert theme="info">
In the case of this reference field, we created a one-way reference because we don't want to create a reverse field in the models we created earlier; and we allowed multiple values because without that we'd only be able to add a single card to our grid.
</Alert>

The final step will be to add `Enumeration` fields so we can later select the gap size between cards and the theme. 

Let's start with the gap size. We'll find the `Enumeration` field on the **Add fields** right sidebar, and use the following information to create it:

| Tab      | Field        | Input                                     |
| -------- | ------------ | ----------------------------------------- |
| Settings | Display Name | Cards gap                                 |
| Settings | API ID       | cardsGap                                  |
| Settings | Enumeration  | Select "Cards gap" from the dropdown menu |

![Card grid with references - Gap](/images/docs/recipes/card-grid/cardgrid-references-gap.png)

We'll click `Add` to save.

Finally, we'll repeat the process to add the theme enumeration field:

| Tab      | Field        | Input                                 |
| -------- | ------------ | ------------------------------------- |
| Settings | Display Name | Theme                                 |
| Settings | API ID       | theme                                 |
| Settings | Enumeration  | Select "Theme" from the dropdown menu |

![Card grid with references - Theme](/images/docs/recipes/card-grid/cardgrid-references-theme.png)

We'll click `Add` to save.

We've created a card grid component that contains several schema elements for customization purposes and that lets us add existing content entries as cards.

![Card grid with references](/images/docs/recipes/card-grid/cardgrid-references-fields.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our card grid recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

[Learn how to create a card grid with nested components that allows you to dynamically select between different card types!](/docs/recipes/card-grid/card-grid-components/)
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>


---
# Cards grid overview

Source: https://hygraph.com/docs/recipes/card-grid/section-index

## Overview

In this section, you will find recipes that you can use to create **card grids** using different field configurations.

| Recipe                                                                | Description                                                 |
| --------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Card grid with components](/docs/recipes/card-grid/card-grid-components/) | Learn how to create a card grid using components            |
| [Card grid with references](/docs/recipes/card-grid/card-grid-references/) | Learn how to create a card grid using references            |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Card Grid Cookbook

We have prepared a project that contains the entire **Card Grid cookbook**:

<Button
  href="https://app.hygraph.com/clone/5f1ac5e413bd42839cc16cf31071f0a6?name=Hygraph%20Recipes%20-%20Card%20Grid"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create card grids, so you can compare the different card grid configurations without having to clone multiple projects.

This project also contains a demo model that includes all the card grid components as basic component fields, as well as a modular component field that you can use as a card grid type selector.


---
# Simple CTA

Source: https://hygraph.com/docs/recipes/cta/cta-simple

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a simple call to action (CTA) containing a single line text field, a rich text field, and components.

You can use this card if you are looking for a simple format containing only a heading, a body and a button link.

![Simple CTA](/images/docs/recipes/cta/cta-simple.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/cta/cta-simple#clone-project) This is the way to go if you're curious about how the CTAs are made but don't want to follow the step-by-step creation process. This project contains the entire **CTA Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this CTA to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with components and basic component fields. Let's look into these concepts:

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/cta/cta-simple/#step-by-step-guide) Use this guide to create a simple CTA component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/cta/cta-simple/#clone-project) Clone the project that contains the entire **CTA cookbook** to compare the different CTA configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **CTA cookbook**:

<Button
  href="https://app.hygraph.com/clone/8284f276a0e941a2b1aa28d9c1011433?name=Hygraph%20Recipes%20-%20CTAs"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create calls to action, so you can compare the different CTA configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Simple CTA"**.

This project also contains a demo model that includes all the CTA components in the cookbook as basic component fields, as well as a modular component field that you can use as a CTA type selector.

## Step-by-step guide

Before we can build our **simple CTA component**, we need to create a button components that we can later add to our CTA.

The first step is to create the component itself. To do this, we'll navigate to the Schema of our Hygraph project and click `+Add` next to **Components**.

We'll use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Button  |
| API ID        | Button  |
| API ID Plural | Buttons |

![Simple CTA - button component](/images/docs/recipes/cta/cta-simple-buttoncomponent.png)

We'll click `Add component` to save. We can now start adding instances to this component.

Let's start with a `Single line text` field, which will be the label of our button. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Field        | Input       |
| ------------ | ----------- |
| Display Name | Button text |
| API ID       | buttonText  |

![Simple CTA - Button text](/images/docs/recipes/cta/cta-simple-buttontext.png)

We'll click `Add` to save.

Finally, let's add a `Slug` field, which will be our button URL. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Button URL                                                                                                                                                           |
| Settings    | API ID                              | buttonUrl                                                                                                                                                            |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                         |
| Validations | `Make this field required` checkbox | Select this checkbox                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                         |
| Validations | `Match a specific pattern` checkbox | Select this checkbox, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Simple CTA - Button URL](/images/docs/recipes/cta/cta-simple-buttonurl.png)

We'll click `Add` to save.

This is how you build a simple button component in Hygraph. The next step is to create our simple CTA component, where we will include the button component we just created. This is a simple example of how to nest components using Hygraph.

We'll create the simple CTA component using this information:

| Field         | Input      |
| ------------- | ---------- |
| Display Name  | Simple CTA |
| API ID        | SimpleCta  |
| API ID Plural | SimpleCtas |

![Simple CTA component](/images/docs/recipes/cta/cta-simple-component.png)

We'll click `Add component` to save. 

We can now start adding instances to this component. Let's start with a `Single line text` field, which will be the heading of our CTA.

We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Heading              |
| Settings    | API ID                              | heading              |
| Settings    | `Use as title field` checkbox       | Select this checkbox |
| Validations | `Make this field required` checkbox | Select this checkbox |

![Simple CTA component - Heading](/images/docs/recipes/cta/cta-simple-componentheading.png)

We'll click `Add` to save.

Next, we want to be able to add text to our CTA. To achieve this, we'll add a Rich Text field from the right sidebar, using the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Body                 |
| Settings    | API ID                              | body                 |
| Validations | `Make this field required` checkbox | Select this checkbox |

![Simple CTA component - Body](/images/docs/recipes/cta/cta-simple-componentbody.png)

We'll click `Add` to save.

Finally, we'll add a basic component field to include the button component that we created earlier.

We'll find the `Basic component` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                             |
| ----------- | ----------------------------------- | ------------------------------------------------- |
| Settings    | Display Name                        | Button                                            |
| Settings    | API ID                              | button                                            |
| Settings    | Select component                    | Use the dropdown to select the "Button" component |
| Validations | `Make this field required` checkbox | Select this checkbox                              |

![Simple CTA - Nested button component](/images/docs/recipes/cta/cta-simple-component-nestedbutton.png)

We'll click `Add` to save.

Our "Simple CTA" component should look like this:

![Simple CTA](/images/docs/recipes/cta/cta-simple.png)

<Alert theme="info" title="Pro Tip">
We've created a simple CTA component that contains a button component nested in it, as well as other schema elements.

You could potentially reuse this component throughout your project, as needed.
</Alert>

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our CTA recipes.

Check out the next document section for that!

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This recipe shows you how to create a simple CTA component using Hygraph. If you want to try out something more complex, we have a [CTA with social links](/docs/recipes/cta/cta-socials/) and a [styled CTA](/docs/recipes/cta/cta-styled/) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>


---
# CTA with socials

Source: https://hygraph.com/docs/recipes/cta/cta-socials

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a call to action (CTA) with social links containing a heading, a body and a button.

To create it, we will use a single line text field, a rich text field, slugs, enumerations and components.

You can use this CTA to give more visibility to your social networks!

![CTA with socials](/images/docs/recipes/cta/cta-socials.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/cta/cta-socials#clone-project) This is the way to go if you're curious about how the CTAs are made but don't want to follow the step-by-step creation process. This project contains the entire **CTA Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this CTA to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/cta/cta-socials/#step-by-step-guide) Use this guide to create a CTA component with social links that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/cta/cta-socials/#clone-project) Clone the project that contains the entire **CTA cookbook** to compare the different CTA configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **CTA cookbook**:

<Button
  href="https://app.hygraph.com/clone/8284f276a0e941a2b1aa28d9c1011433?name=Hygraph%20Recipes%20-%20CTAs"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create calls to action, so you can compare the different CTA configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"CTA with Social Links"**.

This project also contains a demo model that includes all the CTA components in the cookbook as basic component fields, as well as a modular component field that you can use as a CTA type selector.

## Step-by-step guide

Before we can build our **CTA component with social links**, we need to create a social networks button component that we can later add to our CTA. 

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create a social networks button

The first step is to create this button, so that we can later include it in our CTA component as a field. We'll start by creating an enumeration that will allow us to select a social network from a dropdown menu.

We'll click `+ Add` next to **Enumerations** and use the following information:

| Field        | Input   |
| ------------ | ------- |
| Display Name | Socials |
| API ID       | Socials |

![CTA with socials - Button](/images/docs/recipes/cta/cta-socials-button-enum.png)

We'll click `+ Add` to save.

Next, we need to add enumeration values. These are the options we will get when using this later on as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID    |
| ------------ | --------- |
| Instagram    | instagram |
| Facebook     | facebook  |
| X (Twitter)  | xTwitter  |

![CTA with socials - Button values](/images/docs/recipes/cta/cta-socials-button-enumvalues.png)

Finally, we'll click `Add enumeration` to save.

For the second step, we'll create a socials link component. We'll click `+ Add` next to **Components** and use the following information:

| Field         | Input       |
| ------------- | ----------- |
| Display Name  | Social link |
| API ID        | SocialLink  |
| API ID Plural | SocialLinks |

![CTA with socials - Link component](/images/docs/recipes/cta/cta-socials-button-linkcomponent.png)

We'll click `Add component` to save. We can now start adding instances to this component.

Let's start with an `Enumeration` field, which will be our dropdown menu. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                   |
| ----------- | ----------------------------------- | --------------------------------------- |
| Settings    | Display Name                        | Social icon                             |
| Settings    | API ID                              | socialIcon                              |
| Settings    | Enumeration                         | Select "Socials" from the dropdown menu |
| Validations | `Make this field required` checkbox | Select this checkbox                    |

![CTA with socials - Icon dropdown](/images/docs/recipes/cta/cta-socials-button-icondropdown.png)

We'll click `Add` to save.

With this configuration, we've ensured that our enumeration field will use the social icons enumeration we created earlier, and will also be a required field.

Finally, let's add a **Slug** field, which will be our socials URL. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | URL                                                                                                                                                                  |
| Settings    | API ID                              | url                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                         |
| Settings    | `Use as title field` checkbox       | Select this checkbox                                                                                                                                                 |
| Validations | `Make this field required` checkbox | Select this checkbox                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                         |
| Validations | `Match a specific pattern` checkbox | Select this checkbox, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![CTA with socials - Button URL](/images/docs/recipes/cta/cta-socials-button-buttonurl.png)

We'll click `Add` to save.

This is how you build a simple social links button component in Hygraph. The next step is to create our CTA component with social buttons, where we will include the component we just created. This is a simple example of how to nest components using Hygraph.

### 2. Create a CTA component with social links

It is time to create the CTA component with social links. We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input                 |
| ------------- | --------------------- |
| Display Name  | CTA with social links |
| API ID        | CtaWithSocialLinks    |
| API ID Plural | CtaWithSocialLinkss   |

![CTA with socials - Component](/images/docs/recipes/cta/cta-socials-component.png)

We'll click `Add component` to save. 

We can now start adding instances to this component. Let's start with a `Single line text` field, which will be the heading of our CTA. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Heading              |
| Settings    | API ID                              | heading              |
| Settings    | `Use as title field` checkbox       | Select this checkbox |
| Validations | `Make this field required` checkbox | Select this checkbox |

![CTA component with socials - Heading](/images/docs/recipes/cta/cta-socials-heading.png)

We'll click `Add` to save.

Next, we want to be able to add text to our CTA. To achieve this, we'll add a `Rich Text field` from the right sidebar, using the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Body                 |
| Settings    | API ID                              | body                 |
| Validations | `Make this field required` checkbox | Select this checkbox |

![CTA component with socials - Body](/images/docs/recipes/cta/cta-socials-body.png)

We'll click `Add` to save.

Finally, we'll add a basic component field to include the social link component that we created earlier.

We'll find the `Basic component` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab      | Field                            | Input                                                  |
| -------- | -------------------------------- | ------------------------------------------------------ |
| Settings | Display Name                     | Socials button                                         |
| Settings | API ID                           | socialsButton                                          |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                   |
| Settings | Select component                 | Use the dropdown to select the "Social link" component |

![CTA component with socials - Nested link component](/images/docs/recipes/cta/cta-socials-nestedbutton.png)

We'll click `Add` to save.

<Alert theme="info" title="Pro Tip">
We've created a CTA component with socials that contains a links component nested in it, as well as other schema elements.

You could potentially reuse this component throughout your project, as needed.
</Alert>

![CTA with socials](/images/docs/recipes/cta/cta-socials.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our CTA recipes.

Check out the next document section for that!

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)
- [Enumerations](/docs/developer-guides/schema/using-enumerations)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

- [Simple CTA:](/docs/recipes/cta/cta-simple/) Learn how to build a basic CTA component containing a title, some text and a button link.
- [Styled CTA:](/docs/recipes/cta/cta-styled/) Learn how to build a CTA component that uses dropdown fields for style selection, and contains a title, a body and a button link.
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Styled CTA

Source: https://hygraph.com/docs/recipes/cta/cta-styled

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a styled call to action (CTA) containing a heading, a body, styling options and a button.

To create this, we will use single line text fields, rich text fields, enumerations and components.

This is the type of CTA you want if the component is meant to be used in different pages in your project which have different styling options available.

Here, by adding styling option dropdown menus, you'll give Editors the possibility to style the CTA using the options you provide.

Dropdowns are great for this, because while they have options, it will only be within a limited selection that ensures the whole project has a cohesive look & feel.

![Styled CTA](/images/docs/recipes/cta/cta-styled.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/cta/cta-styled#clone-project) This is the way to go if you're curious about how the CTAs are made but don't want to follow the step-by-step creation process. This project contains the entire **CTA Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this CTA to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/cta/cta-styled/#step-by-step-guide) Use this guide to create a styled CTA component that you can reuse across different models in your Hygraph projects.
- [Path 2:](/docs/recipes/cta/cta-styled/#clone-project) Clone the project that contains the entire **CTA cookbook** to compare the different CTA configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **CTA cookbook**:

<Button
  href="https://app.hygraph.com/clone/8284f276a0e941a2b1aa28d9c1011433?name=Hygraph%20Recipes%20-%20CTAs"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create calls to action, so you can compare the different CTA configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"CTA Styled"**.

This project also contains a demo model that includes all the CTA components in the cookbook as basic component fields, as well as a modular component field that you can use as a CTA type selector.

## Step-by-step guide

Before we can build our **Styled CTA component**, we need to create other schema elements that we can later add to it.

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create a styled button component

We want our CTA to contain a button component that offers styling options, besides the usual URL and label.

We'll start by creating enumerations for size and theme, which will allow us to select how we want the button to look from a dropdown menu.

We'll click `+ Add` next to **Enumerations** and use the following information:

| Field        | Input |
| ------------ | ----- |
| Display Name | Size  |
| API ID       | Size  |

![Styled CTA - Size enumeration](/images/docs/recipes/cta/cta-styled-button-sizeenum.png)

We'll click `+ Add` to save.

Next, we need to add enumeration values. These are the options we will get when using this later on as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Small        | small  |
| Medium       | medium |
| Large        | large  |

![Styled CTA - Size enumeration values](/images/docs/recipes/cta/cta-styled-button-sizeenumvalues.png)

We'll click `Add enumeration` to save.

Next, we need to create an enumeration for theme selection. We'll repeat the process using the following information:

| Field        | Input |
| ------------ | ----- |
| Display Name | Theme |
| API ID       | Theme |

Once more, we need to add enumeration values. For this example, we'll use two theme options - light and dark.

We'll add the following:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

![Styled CTA - Theme enumeration values](/images/docs/recipes/cta/cta-styled-button-themeenumvalues.png)

We'll click `Add enumeration` to save.

For the second step, we'll create our styled button component. We'll click `+ Add` next to **Components** and use the following information:

| Field         | Input         |
| ------------- | ------------- |
| Display Name  | Button styled |
| API ID        | ButtonStyled  |
| API ID Plural | ButtonStyleds |

![Styled CTA - Button component](/images/docs/recipes/cta/cta-styled-button-component.png)

We'll click `Add component` to save. We can now start adding instances to this component.

Let's start with a `single line text` field, which will be the label of our button. You will find it in the **Add fields** right sidebar. 

We'll click on it to add it, using the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Button text          |
| Settings    | API ID                              | buttonText           |
| Settings    | `Use this field as title` checkbox` | Select this checkbox |
| Validations | `Make this field required` checkbox | Select this checkbox |

![Styled CTA - Button label](/images/docs/recipes/cta/cta-styled-button-label.png)

We'll click `Add` to save.

Next, we want to add a `slug` field, for our button URL. We'll find it on the **Add fields** sidebar, and add it using this information:

| Tab         | Field                               | Input                                                                                                                                                                |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | URL                                                                                                                                                                  |
| Settings    | API ID                              | url                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox`               | Leave this checkbox selected                                                                                                                                         |
| Validations | `Make this field required` checkbox | Select this checkbox                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                         |
| Validations | `Match a specific pattern` checkbox | Select this checkbox, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Styled CTA - Button URL](/images/docs/recipes/cta/cta-styled-button-url.png)

We'll click `Add` to save.

Now that we've added our basic fields, we can start adding the enumerations we created earlier. We'll find the `Enumeration` field on the **Add fields** sidebar, and add it using this information:

| Tab         | Field                               | Input                                |
| ----------- | ----------------------------------- | ------------------------------------ |
| Settings    | Display Name                        | Button size                          |
| Settings    | API ID                              | buttonSize                           |
| Settings    | Enumeration                         | Select "Size" from the dropdown menu |
| Validations | `Make this field required` checkbox | Select this checkbox                 |

![Styled CTA - Button size](/images/docs/recipes/cta/cta-styled-button-size.png)

We'll click `Add` to save.

We'll repeat the process for our "theme" enumeration:

| Tab         | Field                               | Input                                 |
| ----------- | ----------------------------------- | ------------------------------------- |
| Settings    | Display Name                        | Button theme                          |
| Settings    | API ID                              | buttonTheme                           |
| Settings    | Enumeration                         | Select "Theme" from the dropdown menu |
| Validations | `Make this field required` checkbox | Select this checkbox                  |

![Styled CTA - Button theme](/images/docs/recipes/cta/cta-styled-button-theme.png)

We'll click `Add` to save.

We've created a styled button component that contains the basic fields for label and URL, and also offers styling options using dropdown menus.

### 2. Create a styled CTA component

Now that we have created the component we want to nest into our styled CTA component, we can start working on this one.

We'll start by creating the component itself, using this information:

| Field         | Input      |
| ------------- | ---------- |
| Display Name  | CTA styled |
| API ID        | CtaStyled  |
| API ID Plural | CtaStyleds |

![Styled CTA component](/images/docs/recipes/cta/cta-styled-component.png)

We'll click `Add component` to save. 

We can now start adding instances to this component. Let's start with a `Single line text` field, which will be the heading of our CTA.

We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Heading              |
| Settings    | API ID                              | heading              |
| Settings    | `Use as title field` checkbox       | Select this checkbox |
| Validations | `Make this field required` checkbox | Select this checkbox |

![Styled CTA component - Heading](/images/docs/recipes/cta/cta-styled-component-heading.png)

We'll click `Add` to save.

Next, we want to be able to add text to our CTA. To achieve this, we'll add a `Rich Text field` from the right sidebar, using the following information:

| Tab         | Field                               | Input                |
| ----------- | ----------------------------------- | -------------------- |
| Settings    | Display Name                        | Body                 |
| Settings    | API ID                              | body                 |
| Validations | `Make this field required` checkbox | Select this checkbox |

![Styled CTA component - Body](/images/docs/recipes/cta/cta-styled-component-body.png)

We'll click `Add` to save.

The next step is to add the enumerations we created earlier. When you create schema elements such as components and enumerations, it is normal to reuse them across your schema.

First, we'll add the "size" enumeration. We'll find the `Enumeration` field on the **Add fields** sidebar, and add it using this information:

| Tab         | Field                               | Input                                |
| ----------- | ----------------------------------- | ------------------------------------ |
| Settings    | Display Name                        | Size                                 |
| Settings    | API ID                              | size                                 |
| Settings    | Enumeration                         | Select "Size" from the dropdown menu |
| Validations | `Make this field required` checkbox | Select this checkbox                 |

![Styled CTA component - Size](/images/docs/recipes/cta/cta-styled-component-size.png)

We'll click `Add` to save.

We'll repeat the process for our "theme" enumeration:

| Tab         | Field                               | Input                                 |
| ----------- | ----------------------------------- | ------------------------------------- |
| Settings    | Display Name                        | Theme                                 |
| Settings    | API ID                              | theme                                 |
| Settings    | Enumeration                         | Select "Theme" from the dropdown menu |
| Validations | `Make this field required` checkbox | Select this checkbox                  |

![Styled CTA component - Theme](/images/docs/recipes/cta/cta-styled-component-theme.png)

We'll click `Add` to save.

Finally, we'll add a basic component field to include the styled button component that we created in the previous step.

We'll find the `Basic component` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab      | Field                          | Input                                                    |
| -------- | ------------------------------ | -------------------------------------------------------- |
| Settings | Display Name                   | Button                                                   |
| Settings | API ID                         | button                                                   |
| Settings | Select component               | Use the dropdown to select the "Button styled" component |
| Settings | `Make field required` checkbox | Select this checkbox                                     |

![Styled CTA component - Nested button component](/images/docs/recipes/cta/cta-styled-component-nestedbutton.png)

We'll click `Add` to save.

<Alert theme="info" title="Pro Tip">
We've created a styled CTA component that contains a styled button component nested in it, as well as other schema elements.

You could potentially reuse this component throughout your project, as needed.
</Alert>

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our CTA recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

- [CTA with social links:](/docs/recipes/cta/cta-socials/) Learn how to build a CTA component containing a title, some text and a button that lets you select a social network and adds a link  to it.
- [Styled CTA:](/docs/recipes/cta/cta-styled/) Learn how to build a CTA component that uses dropdown fields for style selection, and contains a title, a body and a button link.
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# CTA overview

Source: https://hygraph.com/docs/recipes/cta/section-index

## Overview

In this section, you will find recipes that you can use to create **calls to action** using different field configurations.

| Recipe                                                                | Description                                                 |
| --------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Simple CTA](/docs/recipes/cta/cta-simple/)                                | Learn how to create a simple CTA                            |
| [CTA with socials](/docs/recipes/cta/cta-socials/)                         | Learn how to create a CTA with social links                 |
| [Styled CTA](/docs/recipes/cta/cta-styled/)                                | Learn how to create a CTA with style dropdowns              |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## CTA Cookbook

We have prepared a project that contains the entire **CTA cookbook**:

<Button
  href="https://app.hygraph.com/clone/8284f276a0e941a2b1aa28d9c1011433?name=Hygraph%20Recipes%20-%20CTAs"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create calls to action, so you can compare the different CTA configurations without having to clone multiple projects.

This project also contains a demo model that includes all the CTA components in the cookbook as basic component fields, as well as a modular component field that you can use as a CTA type selector.


---
# Blocks FAQ page

Source: https://hygraph.com/docs/recipes/faq/blocks-faq-page

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create an FAQ model that lets you add Q&A pairs as blocks.

You'll create a model to store the Q&A pairs with data, a component for the blocks, and a model that will let you add blocks of topic-based FAQ lists.

![Blocks FAQ Page](/images/docs/recipes/faq/blocks-faq-page.png)

This recipe is a great option if you prefer to work on Q&A pairs as individual content pieces that you can easily add to another model to create the FAQ list. It is also a great option if your users would benefit from a sectioned FAQ landing page that groups questions and answers by topic.

This mock image shows what a frontend using this setup could look like:

![Mock image](/images/docs/recipes/faq/faq-mock-image-block.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Blocks FAQ Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/faq/section-index#faq-cookbook)

This is the way to go if you're curious about how we built the FAQ recipes but don't want to follow the step-by-step creation process. This project contains the entire **FAQ Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Blocks FAQ Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="zoZeTDbidco" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the FAQ list model

This model will let you create Q&A pairs as content entries.

To create the model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | FAQ List Single |
| API ID        | FaqListSingle   |
| API ID Plural | FaqListSingles  |

Click `Add Model` to save.

Let's add fields to this model. We will add a `Single line text` field to use as question, and a `Rich Text` field for the answer. 

For the question, add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Question                     |
| Settings    | API ID                | question                     |
| Settings    | Description           | Write the question here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures all entries are created with their questions as title, for quick identification in the content table. These titles must also be unique, which will contribute to a good user experience for editors creating FAQ lists.

Next, you want include a rich text field for the answer, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                 |
| ----------- | --------------------- | --------------------- |
| Settings    | Display name          | Answer                |
| Settings    | API ID                | answer                |
| Settings    | Description           | Write the answer here |
| Validations | `Make field required` | Select this checkbox  |

Click `Add` to save.

<Alert theme="info">

In this case, we're not enabling embedding because we don't need to insert content from other Q&A pairs or even from other models in our simple setup. Consider enabling embedding if your content can benefit from it.

</Alert>

We chose to create the FAQ list as a model because in a use case like this, we want to create question & answer sets as content entries that can be easily referenced in other models and components later on. In the next step, we will create the **FAQ Block component** with a reference field that connects this model. This will allow editors to quickly link Q&A pairs to form lists.

### 2. Create the block component

To create the component, navigate to the **Schema builder** and click `+Add` next to **Components**. Use the following information:

| Field         | Input     |
| ------------- | --------- |
| Display name  | FAQ Block |
| API ID        | FaqBlock  |
| API ID Plural | FaqBlocks |

Click `Add component` to save.

This component will contain only two fields: a `Single line text` field for the block title, and a `Reference` field to add Q&A pairs from the model you created in the previous step.

We'll start with the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                          |
| ----------- | --------------------- | ------------------------------ |
| Settings    | Display name          | Block title                    |
| Settings    | API ID                | blockTitle                     |
| Settings    | Description           | Add a title for this FAQ Block |
| Settings    | `Use as title field`  | Leave this checkbox selected   |
| Validations | `Make field required` | Select this checkbox           |

Click `Add` to save. We decided to make it required so all blocks contain a title.

Next, you will create a reference field that will allow editors to add Q&A pairs from the model you created in the previous step.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                              |
| --------- | --------------------------------------- | -------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                          |
| Define    | Model to reference                      | use the dropdown to select `FAQ List Single`       |
| Define    | Reference direction                     | Use the radio button to select `One-way reference` |
| Define    | Relation cardinality                    | One to Many                                        |
| Define    | `Allow multiple (…)`                    | Select this checkbox                               |
| Configure | Display name                            | Q&A Pairs                                          |
| Configure | API ID                                  | qAPairs                                            |
| Configure | Description                             | Select Q&A pairs to form a list                    |

Click `Add` to save.

Your component is ready! In the next step, we will add it to a model to create an FAQ landing page that may contain one or more blocks of FAQ. 

### 3. Create the FAQ page model

To create this model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | Blocks FAQ Page |
| API ID        | BlocksFaqPage   |
| API ID Plural | BlocksFaqPages  |

Click `Add Model` to save.

This model will contain only two fields: a `Single line text` field for the page title, and a `Basic component` field to add blocks of Q&A pairs.

First, we'll add the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Page title                   |
| Settings    | API ID                | pageTitle                    |
| Settings    | Description           | FAQ landing page title       |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all FAQ Page entries contain a unique title that will allow easy identification in the content table.

Next, you will add a basic component field that will allow editors to add blocks of questions and answers.

Add a `Basic component` field from the right sidebar, using the following information:

| Tab      | Field                 | Input                                     |
| -------- | --------------------- | ----------------------------------------- |
| Settings | Display name          | FAQ Block                                 |
| Settings | API ID                | faqBlock                                  |
| Settings | Description           | Add an FAQ Block                          |
| Settings | Allow multiple values | Select this checkbox                      |
| Settings | Select a component    | Use the dropdown to select **FAQ Block.** |

Click `Add` to save.

Your model is ready! This is how you build a landing page for FAQ where lists of questions and answers can be added as blocks. 

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9kohu5p07vxccwk0p3z" caption="Resulting content form" />

Editors will be able to easily create FAQ blocks by referencing **Q&A pairs**.

## Useful links

- [**Components documentation**](/docs/developer-guides/schema/components)
- [**References documentation**](/docs/developer-guides/schema/references)

---
# Conditional FAQ list

Source: https://hygraph.com/docs/recipes/faq/conditional-faq-list

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create an FAQ model that lets you create lists of Q&A pairs of different types based on condition.

You'll create sample models to store the Q&A pairs with data, an enumeration to use as a category selector, and a model that lets you add the Q&A pairs through reference fields.

![Conditional FAQ List](/images/docs/recipes/faq/conditional-faq-list.png)

This recipe is a great option if you prefer to work on Q&A pairs as individual content pieces that you can easily add to another model to create the FAQ list. It is also a great option if you need to create different FAQ landing pages covering different topics.

This image shows what a frontend using this setup could look like:

![Potential frontend display](/images/docs/recipes/faq/faq-mock-image-fromwebsite.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Conditional FAQ List** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/faq/section-index#faq-cookbook)

This is the way to go if you're curious about how we built the FAQ recipes but don't want to follow the step-by-step creation process. This project contains the entire **FAQ Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Conditional FAQ List model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Enumerations:** An enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="ivFx8ilhKsI" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the FAQ category models

We will create 3 models that will let you create Q&A pairs as content entries.

To create the first model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                |
| ------------- | -------------------- |
| Display name  | FAQ Category General |
| API ID        | FaqCategoryGeneral   |
| API ID Plural | FaqCategoryGenerals  |

Click `Add Model` to save.

Let's add fields to this model. We will add a `Single line text` field to use as question, and a `Rich Text` field for the answer, since it allows some formatting. 

For the question, add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Question                     |
| Settings    | API ID                | question                     |
| Settings    | Description           | Write the question here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures all entries are created with their questions as title, for quick identification in the content table. These titles must also be unique, which will contribute to a good user experience for editors creating FAQ lists.

Next, you want include a rich text field for the answer, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                 |
| ----------- | --------------------- | --------------------- |
| Settings    | Display name          | Answer                |
| Settings    | API ID                | answer                |
| Settings    | Description           | Write the answer here |
| Validations | `Make field required` | Select this checkbox  |

Click `Add` to save.

<Alert theme="info">

In this case, we're not enabling embedding because we don't need to insert content from other Q&A pairs or even from other models in our simple setup. Consider enabling embedding if your content can benefit from it.

</Alert>

Since our 3 FAQ category models will contain the same set of fields - a `Single line text` field and a `Rich Text` field - we will go ahead, and duplicate the model that we've just created, and then edit its details.

In the **FAQ category General** model, click the 3 dots context menu at the top of the screen, and select `Duplicate`.

![Duplicate the model](/images/docs/recipes/faq/conditional-faq-list-duplicate.png)

The system will duplicate the model and will rename it to **Copy of FAQ Category General.**

Click on the `Settings` tab at the top and replace the existing information with the following:

| Field         | Input                |
| ------------- | -------------------- |
| Display name  | FAQ Category Billing |
| API ID        | FaqCategoryBilling   |
| API ID Plural | FaqCategoryBillings  |

Click `Update Model` to save.

You'll now duplicate this model following the same process as before, and replace the information under `Settings` with the following:

| Field         | Input                  |
| ------------- | ---------------------- |
| Display name  | FAQ Category Technical |
| API ID        | FaqCategoryTechnical   |
| API ID Plural | FaqCategoryTechnicals  |

Click `Update Model` to save.

We chose to create these category models because we want to create question & answer sets as content entries that can be easily referenced in other models and components later on. Having three separate models, allows us to keep the Q&A pairs separated by topic.

In the next step, we will create an enumeration that will allow content editors to select a category using a dropdown menu. 

### 2. Create the enumeration

To create the component, navigate to the **Schema builder** and click `+Add` next to **Enumerations**. Use the following information:

| Field        | Input             |
| ------------ | ----------------- |
| Display name | Category selector |
| API ID       | CategorySelector  |

Before we can save, we need to add enumeration values, which are the options editors will get when using this later as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID    |
| ------------ | --------- |
| General      | general   |
| Technical    | technical |
| Billing      | billing   |

Finally, click `Add enumeration` to save.

In the next step, we will create the final model, and we'll use this enumeration to set conditional visibility for reference fields that will link to the FAQ category models.

### 3. Create the final model

To create this model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                |
| ------------- | -------------------- |
| Display name  | Conditional FAQ List |
| API ID        | ConditionalFaqList   |
| API ID Plural | ConditionalFaqLists  |

Click `Add Model` to save.

This model will contain a `Single line text` field for the page title, an enumeration to set conditional visibility, and 3 reference fields linking to the FAQ category models you created earlier.

First, we'll add the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Title                        |
| Settings    | API ID                | title                        |
| Settings    | Description           | Write a title here           |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all FAQ Page entries contain a title that will allow easy identification in the content table.

Next, you will add the enumeration.  Find the `Enumeration` field on the right sidebar, click `Add`, and use the following information to create the enumeration:

| Tab      | Field        | Input                                                |
| -------- | ------------ | ---------------------------------------------------- |
| Settings | Display name | FAQ                                                  |
| Settings | API ID       | faq                                                  |
| Settings | Enumeration  | Use the dropdown menu to select `Category selector`. |
| Settings | Description  | Use this dropdown menu to select an FAQ category     |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">

For the purpose of this example, we're not allowing multiple values. If your FAQ landing pages need to add Q&A pairs from more than one category model, you should allow multiple values here.

</Alert>

This enumeration field will allow us to set conditions for the 3 reference fields we're about to add. We did not make this field required because conditional visibility does not support required fields.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                                                                                  |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                                              |
| Define    | Model to reference                      | Use the dropdown to select `FAQ Category Billing`.                                                     |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                                     |
| Define    | Relation cardinality                    | One to many                                                                                            |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                                   |
| Configure | Display name                            | FAQ Category Billing                                                                                   |
| Configure | API ID                                  | faqCategoryBilling                                                                                     |
| Configure | Description                             | Select Q&A pairs                                                                                       |
| Configure | Show based on condition                 | Select this checkbox and then under “Show field if” use the dropdown menus to select `FAQ is Billing`. |

Click `Add` to save.

This reference configuration will allow editors to add links to multiple content entries, but only from the selected model. The way we configured conditional visibility means that this field will only be visible in the content form if the editor selects `Billing` from the dropdown menu that we configured in the previous step.

Now let's add a reference field for the **FAQ Category General** model, using the following information:

| Tab       | Field                                   | Input                                                                                                  |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                                              |
| Define    | Model to reference                      | Use the dropdown to select `FAQ Category General`.                                                     |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                                     |
| Define    | Relation cardinality                    | One to many                                                                                            |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                                   |
| Configure | Display name                            | FAQ Category General                                                                                   |
| Configure | API ID                                  | faqCategoryGeneral                                                                                     |
| Configure | Description                             | Select Q&A pairs                                                                                       |
| Configure | Show based on condition                 | Select this checkbox and then under “Show field if” use the dropdown menus to select `FAQ is General`. |

Click `Add` to save.

We'll add one final reference field for the **FAQ Category Technical** model, using the following information:

| Tab       | Field                                   | Input                                                                                                    |
| --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                                                |
| Define    | Model to reference                      | Use the dropdown to select `FAQ Category Technical`.                                                     |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                                       |
| Define    | Relation cardinality                    | One to many                                                                                              |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                                     |
| Configure | Display name                            | FAQ Category Technical                                                                                   |
| Configure | API ID                                  | faqCategoryTechnical                                                                                     |
| Configure | Description                             | Select Q&A pairs                                                                                         |
| Configure | Show based on condition                 | Select this checkbox and then under “Show field if” use the dropdown menus to select `FAQ is Technical`. |

Click `Add` to save.

Your model is ready! You've built a landing page for FAQ where editors can use a dropdown menu to select a category that will enable reference fields to add lists of Q&A pairs. 

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9itjasy07w537zxvucm" caption="Resulting content form" />

Editors will be able to select a category, which will display the related reference field. They will then be able to use that reference field to link Q&A pairs and create a list.

## Useful links

- [**Components documentation**](/docs/developer-guides/schema/components)
- [**References documentation**](/docs/developer-guides/schema/references)

---
# Reference FAQ component

Source: https://hygraph.com/docs/recipes/faq/reference-faq-component

## Overview

<Alert theme="success" title="Do you have suggestions?">
  <Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link>
  <span> to suggest new recipe ideas!</span>
</Alert>

This guide shows how to create an FAQ component to create lists of pre-defined Q&A pairs. This component can be used in any model in your project.

You'll create a model that contains the data for the Q&A pairs and a component that lets you create a list of questions and answers, adding this information through a reference field.

![Reference FAQ Component](/images/docs/recipes/faq/reference-faq-component.png)

This recipe is a great option if you prefer to work on Q&A pairs as individual content pieces that you can easily add to models or components to create the FAQ list. It is also a great option if you need to show different sets of Q&A pairs throughout your website, as it allows you to take the resulting component, and add it to any model in your project.

This mock image shows what a frontend using this setup could look like:

![Mock Image](/images/docs/recipes/faq/faq-mock-image-single.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Reference FAQ Component**. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
  - Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when
  adding a recipe to your own project. - Are you new to Hygraph? You may want to
  check out our [**Getting Started
  Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/faq/section-index#faq-cookbook)

This is the way to go if you're curious about how we built the FAQ recipes but don't want to follow the step-by-step creation process. This project contains the entire **FAQ Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Reference FAQ Component**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="8drbKvEW_B4" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the FAQ list model

This model will let you create Q&A pairs as content entries.

To create the model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | FAQ List Single |
| API ID        | FaqListSingle   |
| API ID Plural | FaqListSingles  |

Click `Add Model` to save.

Now that the model has been created, you can start adding fields to it.

We will add a `Single line text` field to use as question, and a `Rich Text` field for the answer.

Let's start with the question. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Question                     |
| Settings    | API ID                | question                     |
| Settings    | Description           | Write the question here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

Next, you want include a rich text field for the answer, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                 |
| ----------- | --------------------- | --------------------- |
| Settings    | Display name          | Answer                |
| Settings    | API ID                | answer                |
| Settings    | Description           | Write the answer here |
| Validations | `Make field required` | Select this checkbox  |

Click `Add` to save.

<Alert theme="info">

In this case, we're not enabling embedding because we don't need to insert content from other Q&A pairs or even from other models in our simple setup. Consider enabling embedding if your content can benefit from it.

</Alert>

We chose to create the FAQ list as a model because in a use case like this, we want to create question & answer sets as content entries that can be easily referenced in other models or components later on. In the next step, we will create the **Reference FAQ Component,** which will contain a reference field that connects this model. This will allow editors to quickly set up lists of Q&A pairs.

### 3. Create the Reference FAQ Component

To create the component, navigate to the **Schema builder** and click `+Add` next to **Components**. Use the following information:

| Field         | Input                   |
| ------------- | ----------------------- |
| Display name  | Reference FAQ Component |
| API ID        | ReferenceFaqComponent   |
| API ID Plural | ReferenceFaqComponents  |

Click `Add component` to save.

This component will contain only two fields: a `Single line text` field for the FAQ section title, and a `Reference` field to add lists of Q&A from the model you created in the previous step.

Let's start with the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab      | Field                | Input                        |
| -------- | -------------------- | ---------------------------- |
| Settings | Display name         | FAQ Section title            |
| Settings | API ID               | faqSectionTitle              |
| Settings | Description          | Write a section title here   |
| Settings | `Use as title field` | Leave this checkbox selected |

Click `Add` to save.

Next, you will create a reference field that will allow editors to add Q&A pairs from the model you created in the previous step.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                              |
| --------- | --------------------------------------- | -------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                          |
| Define    | Model to reference                      | use the dropdown to select `FAQ List Single`       |
| Define    | Reference direction                     | Use the radio button to select `One-way reference` |
| Define    | Relation cardinality                    | One to Many                                        |
| Define    | `Allow multiple (…)`                    | Select this checkbox                               |
| Configure | Display name                            | Q&A Pair                                           |
| Configure | API ID                                  | qAPair                                             |
| Configure | Description                             | Link a Q&A pair or create a new one                |

Click `Add` to save.

Your component is ready! This is how you build an FAQ component that uses references to link Q&A pairs.

<Alert theme="info" title="Pro Tip">

You could also add the same set of fields to a model rather than a component to create FAQ landing pages. We explore this idea in our [Simple FAQ Page recipe](/docs/recipes/faq/simple-faq-page).

</Alert>

## Resulting content form

If you were to use this component in a model, the component section of the resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9mxhu5x07vxfuxw5s5w" caption="Resulting content form" />

Editors will be able to easily link existing Q&A pairs from the **FAQ List** model.

## Useful links

- [**Components documentation**](/docs/developer-guides/schema/components)
- [**References documentation**](/docs/developer-guides/schema/references)


---
# FAQ overview

Source: https://hygraph.com/docs/recipes/faq/section-index

This section contains recipes for creating FAQ models & components with different field configurations.

| Recipe                                                               | Description                                                                                      |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Blocks FAQ Page](/docs/recipes/faq/blocks-faq-page)                 | FAQ Model that lets you add different sets of FAQ as blocks.                                     |
| [Conditional FAQ List](/docs/recipes/faq/conditional-faq-list)       | FAQ Model that lets you select from different tables of predefined Q&A pairs based on condition. |
| [Reference FAQ Component](/docs/recipes/faq/reference-faq-component) | FAQ Component that lets you form a list of predefined Q&A pairs.                                 |
| [Sectioned FAQ Page](/docs/recipes/faq/sectioned-faq-page)           | FAQ model that lets you add lists of topic-based Q&A lists.                                      |
| [Simple FAQ Page](/docs/recipes/faq/simple-faq-page)                 | FAQ model that lets you add a list of Q&A pairs.                                                 |

## FAQ cookbook

Cloning the entire cookbook is a great option if you're curious about the content of the FAQ pages & components but don't want to follow the step-by-step creation process.

<Button
  href="https://app.hygraph.com/clone/6b7141a2b9f041fea6f08b3b07c33a09?name=Hygraph%20Recipes%20-%20FAQ"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cloneable project contains the entire FAQ Cookbook, so you can compare recipes or examine their contents.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)

</Alert>

---
# Sectioned FAQ page

Source: https://hygraph.com/docs/recipes/faq/sectioned-faq-page

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create an FAQ model that lets you add pre-created lists of Q&A pairs as sections.

You'll create a component as a template for the Q&A pairs, a model to store the Q&A pairs with data as lists with a title, and a model to let you create entries where you add this information through reference fields.

![Sectioned FAQ page](/images/docs/recipes/faq/sectioned-faq-page.png)

This recipe is a great option if you prefer to work on Q&A lists as individual content pieces that you can easily add to another model to create topic-based FAQ sections on a page. It is also a great option if you need to show different sets of Q&A pairs throughout your website, as it allows you to create content entries grouping different configurations of questions and answers.

This image shows what a frontend using this setup could look like:

![What this could look like on the frontend](/images/docs/recipes/faq/faq-mock-image-fromwebsite-sections.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Sectioned FAQ Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/faq/section-index#faq-cookbook)

This is the way to go if you're curious about how we built the FAQ recipes but don't want to follow the step-by-step creation process. This project contains the entire **FAQ Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Sectioned FAQ Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="aTJBMRXzH9U" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Build the component

We will create a component that will allow us to create different sets of questions and answers.

![Simple FAQ component](/images/docs/recipes/faq/simple-faq-component.png)

In the **Schema builder**, click `+Add` next to **Components** and use the following information:

| Field         | Input                |
| ------------- | -------------------- |
| Display name  | Simple FAQ Component |
| API ID        | SimpleFaqComponent   |
| API ID Plural | SimpleFaqComponents  |

Click `Add component to` save.

Now that you've created the component itself, it's time to add fields to it. This will be a very simple component that only contains a `Single line text` field for the question, and a `Rich Text` field for the answer.

We'll start with the question. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Question                     |
| Settings    | API ID                | question                     |
| Settings    | Description           | Write the question here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This field configuration ensures that editors won't be able to repeat the exact same question on a list.

Next, you want include a rich text field for the answer, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input                 |
| -------- | ------------ | --------------------- |
| Settings | Display name | Answer                |
| Settings | API ID       | answer                |
| Settings | Description  | Write the answer here |

Click `Add` to save.

<Alert theme="info">

In this case, we're not enabling embedding because we don't need to insert content from other Q&A pairs or even from other models in our simple setup. Consider enabling embedding if your content can benefit from it.

</Alert>

Now that our simple FAQ component is ready, we can create the first model.

### 2. Create the FAQ list model

This model will let you create lists of Q&A pairs as content entries.

To create the model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input          |
| ------------- | -------------- |
| Display name  | FAQ List Group |
| API ID        | FaqListGroup   |
| API ID Plural | FaqListGroups  |

Click `Add Model` to save.

Now that the model has been created, you can start adding fields to it. 

We will add a `Single line text` field to use as title, and a `Basic component` field to hold the component that we created in the previous step. 

Let's start with the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | FAQ Title                    |
| Settings    | API ID                | faqTitle                     |
| Settings    | Description           | FAQ group title              |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that editors can't create lists without a unique name.

It's time to add the **Simple FAQ component** that you built earlier. Add a `Basic component` field from the right sidebar, using the following information:

| Tab      | Field                 | Input                                                |
| -------- | --------------------- | ---------------------------------------------------- |
| Settings | Display name          | Q&A Pair                                             |
| Settings | API ID                | qAPair                                               |
| Settings | Description           | Add a pair of question and answer fields             |
| Settings | Allow multiple values | Select this checkbox                                 |
| Settings | Select a component    | Use the dropdown to select **Simple FAQ Component**. |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">

While you could have added the Q&A fields manually rather than use a component field, this setup simplifies adding the repeated set of fields over and over.

</Alert>

We chose to create the FAQ list as a model because in a use case like this, we want to create question & answer sets as content entries that can be easily referenced in other models later on. In the next step, we will create the **Sectioned** **FAQ Page Model** with a reference field that connects this model, which will allow editors to quickly set up FAQ landing pages containing topic-based FAQ sections.

### 3. Create the FAQ page model

To create the FAQ page model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input              |
| ------------- | ------------------ |
| Display name  | Sectioned FAQ Page |
| API ID        | SectionedFaqPage   |
| API ID Plural | SectionedFaqPages  |

Click `Add Model` to save.

This model will contain only two fields: a `Single line text` field for the page title, and a `Reference` field to add lists of Q&A from the model you created in the previous step.

Let's start with the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Page title                   |
| Settings    | API ID                | pageTitle                    |
| Settings    | Description           | Write a page title here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all FAQ Page entries contain a unique title that will allow easy identification in the content form.

Next, you will create a reference field that editors can use to add content entries from the model you created in the previous step.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                              |
| --------- | --------------------------------------- | -------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                          |
| Define    | Model to reference                      | use the dropdown to select `FAQ List Group`        |
| Define    | Reference direction                     | Use the radio button to select `One-way reference` |
| Define    | Relation cardinality                    | One to many                                        |
| Define    | `Allow multiple (…)`                    | Select this checkbox                               |
| Configure | Display name                            | FAQ List                                           |
| Configure | API ID                                  | faqList                                            |
| Configure | Description                             | Select a list of questions and answers             |

Click `Add` to save.

Your model is ready! This is how you build a **Sectioned FAQ Page model** that lets you add lists of questions & answers to a content entry. You can use this in your front end in different ways, such as rich text embeds or landing pages.

<Alert theme="info" title="Pro Tip">

You could also add the same set of fields to a component rather than a model to reuse as a template for an FAQ list block.

</Alert>

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9p0jat607w5hjpkqo1w" caption="Resulting content form" />

Editors will be able to easily create FAQ pages by referencing lists from the **FAQ List** model. The FAQ Pages they create could contain a single Q&A list, or several ones.

## Useful links

- [**Components documentation**](/docs/developer-guides/schema/components)
- [**References documentation**](/docs/developer-guides/schema/references)

---
# Simple FAQ page

Source: https://hygraph.com/docs/recipes/faq/simple-faq-page

## Overview

<Alert theme="success" title="Do you have suggestions?">
  <Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link>
  <span> to suggest new recipe ideas!</span>
</Alert>

This guide shows how to create an FAQ model that lets you add pre-created Q&A pairs to form a list.

You'll create two models: one model to store the Q&A pairs, and a model that will let you add Q&A pairs through reference fields to form a list.

![Simple FAQ page](/images/docs/recipes/faq/simple-faq-page.png)

This recipe is a great option if you prefer to work on Q&A pairs as individual content pieces that you can easily add to another model to create the FAQ list.

This mock image shows what a frontend using this setup could look like:

![Mock image](/images/docs/recipes/faq/faq-mock-image-single.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Simple FAQ Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
  - Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when
  adding a recipe to your own project. - Are you new to Hygraph? You may want to
  check out our [**Getting Started
  Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/faq/section-index#faq-cookbook)

This is the way to go if you're curious about how we built the FAQ recipes but don't want to follow the step-by-step creation process. This project contains the entire **FAQ Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Simple FAQ Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="YcRg3DFZMOo" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the FAQ list model

This model will let you create Q&A pairs as content entries.

To create the model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | FAQ List Single |
| API ID        | FaqListSingle   |
| API ID Plural | FaqListSingles  |

Click `Add Model` to save.

Now that the model has been created, you can start adding fields to it.

We will add a `Single line text` field to use as question, and a `Rich Text` field for the answer.

Let's start with the question. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Question                     |
| Settings    | API ID                | question                     |
| Settings    | Description           | Write the question here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

Next, you want include a rich text field for the answer, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                 |
| ----------- | --------------------- | --------------------- |
| Settings    | Display name          | Answer                |
| Settings    | API ID                | answer                |
| Settings    | Description           | Write the answer here |
| Validations | `Make field required` | Select this checkbox  |

Click `Add` to save.

<Alert theme="info">

In this case, we're not enabling embedding because we don't need to insert content from other Q&A pairs or even from other models in our simple setup. Consider enabling embedding if your content can benefit from it.

</Alert>

We chose to create the FAQ list as a model because in a use case like this, we want to create question & answer sets as content entries that can be easily referenced in other models later on. In the next step, we will create the **Simple FAQ Page Model** with a reference field that connects this model, which will allow editors to quickly set up FAQ landing pages using existing data.

### 3. Create the FAQ page model

To create the **FAQ Page** model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | Simple FAQ Page |
| API ID        | SimpleFaqPage   |
| API ID Plural | SimpleFaqPages  |

Click `Add Model` to save.

This model will contain only two fields: a `Single line text` field for the page title, and a `Reference` field to add Q&A pairs from the model you created in the previous step.

Let's start with the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Page title                   |
| Settings    | API ID                | pageTitle                    |
| Settings    | Description           | Write a page title here      |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all FAQ Page entries contain a unique title that will allow easy identification in the content form.

Next, you will create a reference field that will allow editors to add content entries from the model you created in the previous step.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                              |
| --------- | --------------------------------------- | -------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                          |
| Define    | Model to reference                      | use the dropdown to select `FAQ List Single`       |
| Define    | Reference direction                     | Use the radio button to select `One-way reference` |
| Define    | Relation cardinality                    | One to Many                                        |
| Define    | `Allow multiple (…)`                    | Select this checkbox                               |
| Configure | Display name                            | Q&A Pair                                           |
| Configure | API ID                                  | qAPair                                             |
| Configure | Description                             | Select Q&A pairs                                   |

Click `Add` to save.

Your model is ready! This is how you build a **Simple FAQ Page model** that lets you easily add Q&A pairs through a reference field.

<Alert theme="info" title="Pro Tip">

You could also add the same set of fields to a component rather than a model to reuse as a template for an FAQ list block. We explore this idea in our [Reference FAQ Component recipe](/docs/recipes/faq/reference-faq-component).

</Alert>

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9r1hu6507vxlueil59b" caption="Resulting content form" />

Editors will be able to easily create FAQ pages by referencing Q&A pairs from the **FAQ List** model.

## Useful links

- [**References documentation**](/docs/developer-guides/schema/references)


---
# Footer with links

Source: https://hygraph.com/docs/recipes/headers-and-footers/footer-links

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a footer component containing images, components and relations.

It will allow you to create a footer that contains a one-liner message, a company contact link, an image, and multiple links to both internal and external resources, as well as to your company's socials.

![Footer component with fields](/images/docs/recipes/headers-and-footers/footer-links.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/headers-and-footers/footer-links#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create this footer, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/headers-and-footers/footer-links#clone-the-complete-cookbook) This is the way to go if you're curious about how the headers & footers are made but don't want to follow the step-by-step creation process. This project contains the entire **Headers & footers Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this footer to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models and adding fields, reusable components, and sidebar widgets to them, as well as integrating remote sources and establishing relationships with other models.

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/headers-and-footers/footer-links#step-by-step-guide) Use this guide to create a footer component with links that you can use in your project.
- [Path 2:](/docs/recipes/headers-and-footers/footer-links#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the headers & footers right away, or you can clone the project that contains the entire **Headers & footers cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to create your headers & footers, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/b0e53354c48646f6ac6c32b02a2c2f2b?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/headers-and-footers/footer-links#4-create-the-footer).

### Clone the complete cookbook

We have prepared a project that contains the entire **Headers & footers cookbook**:

<Button
  href="https://app.hygraph.com/clone/05309f493150431d9b943111f1db3c5f?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create headers & footers, so you can compare the different field configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Footer links"** component.

## Step-by-step guide

In this guide, we will create a footer component with a nested component field for links. Before we can build our footer component, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create the referenced models:** We will create 3 sample models - Author, Book, and Shop - to use in our internal links.
2. **Create the navigation item component:** We will build a navigation item component that we can nest into our footer component to add links.
3. **Create the Socials model:** We will create a model that will allow us to create content entries with links ot our social network accounts.
4. **Create the footer component:** We will create a footer component that you can later add as component field to your models.

### 1. Create the basic models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic schema elements that you will need for this recipe! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to the final section](/docs/recipes/headers-and-footers/footer-links#4-create-the-footer) to continue the tutorial.

</Alert>

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/headers-and-footers/author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/headers-and-footers/book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/headers-and-footers/shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create our links component!

### 2. Create the navigation item component

![Create a navigation item component](/images/docs/recipes/headers-and-footers/navigation-item-component.png)

We want our footer to contain a navigation item component that will allow us to add multiple links - both internal and external - to our footer. To build this, we'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input           |
| ------------- | --------------- |
| Display Name  | Navigation item |
| API ID        | NavigationItem  |
| API ID Plural | NavigationItems |

We'll click `Add component` to save. It's time to start adding instances to this component.

First, we'll add a `Single line text` field from the **Add fields** right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                |
| -------- | ----------------------------- | -------------------- |
| Settings | Display Name                  | Link label           |
| Settings | API ID                        | linkLabel            |
| Settings | `Use as title field` checkbox | Select this checkbox |

We'll click `Add` to save.

We want our footer to offer the possibility to add both internal and external links. To do this, we'll add a reference for the internal links, and a slug field for the external ones. In this case, we won't be making them required fields, because users will either use one or the other.

We'll start with the reference field. We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                | Input                                                              |
| ------------------- | -------------------- | ------------------------------------------------------------------ |
| Define              | Reference type       | Select `Allow multiple models to be referenced (Union Type)`       |
| Define              | Models to reference  | Use the dropdown menu to select `Author`, `Book` and `Shop` |
| Define              | Reference direction  | Select `One-way reference`                                         |
| Define              | Relation cardinality | Select  `One to One`                                               |
| Configure reference | Display Name         | Internal link                                                               |
| Configure reference | API ID               | internalLink                                                               |

We'll click `Add` to save. We've configured the reference in such a way that when we find this field in a content entry, it will allow us to select an entry from the models that we selected.

Next, we'll add a `slug` field for our external URLs, using the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External URL                                                                                                                                                                 |
| Settings    | API ID                              | externalUrl                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

Finally, we want to have a boolean field that we can then toggle to indicate if a link should open on a separate tab or not.

We'll add a `boolean` field using the following information:

| Tab      | Field        | Input           |
| -------- | ------------ | --------------- |
| Settings | Display Name | New tab |
| Settings | API ID       | newTab   |

We'll click `Add` to save. 

### 3. Create the Socials model

![Socials model](/images/docs/recipes/headers-and-footers/socials-model.png)

We will create a **Socials** model that will allow us to create different social network content entries that we can later on add to our footer as relations.

In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input    |
| ------------- | -------- |
| Display Name  | Socials  |
| API ID        | Socials  |
| API ID Plural | Socialss |

We'll click `Add model` to save, and start adding fields to this model.

We'll start with the social network name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                            |
| -------- | ----------------------------- | -------------------------------- |
| Settings | Display Name                  | Social network name              |
| Settings | API ID                        | socialNetworkName                |
| Settings | Description                   | Add the social network name here |
| Settings | `Use as title field` checkbox | Leave this checkbox selected     |

We'll click `Add` to save.

Next, we'll add a `Slug` field from the right sidebar, which will allow us to later on include URLs to link to our socials.

We'll use the following information:

| Tab         | Field                               | Input                                                                                                                                                                |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Social network URL                                                                                                                                                   |
| Settings    | API ID                              | socialNetworkUrl                                                                                                                                                     |
| Settings    | Description                         | Add the social network URL here                                                                                                                                      |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                         |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                         |
| Validations | `Match a specific pattern` checkbox | Select this checkbox, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field from the right sidebar, so we can include the social network icon as well.

We'll use the following information:

| Tab      | Field        | Input                            |
| -------- | ------------ | -------------------------------- |
| Settings | Display Name | Social network icon              |
| Settings | API ID       | socialNetworkIcon                |
| Settings | Description  | Add the social network icon here |

We'll click `Add` to save. We did not allow multiple values in this case, because we want to only be able to have one icon per social account.

Now that we have created all the schema elements that we needed for our footer, let's jump into the final step!

### 4. Create the footer

<VideoEmbed videoId="if4SqKQph24" />

Now that we have all the schema elements that, both directly and indirectly, will be a part of our final footer component, we'll go ahead and create it!

![Footer component with fields](/images/docs/recipes/headers-and-footers/footer-links.png)

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input        |
| ------------- | ------------ |
| Display Name  | Footer links |
| API ID        | FooterLinks  |
| API ID Plural | FooterLinkss |

We'll click `Add component` to save, and then we'll start adding instances to it.

We want our footer to start with a CTA for customers to contact us. It will contain a one-liner message, an image and a contact URL. 

We'll start with the one liner message. Let's add a `Single line text` field, which will be our footer title. We'll add it by clicking `Add` on the `Single line text` field card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Footer title                 |
| Settings | API ID                        | footerTitle                  |
| Settings | Description                   | Add a one-liner message here |
| Settings | `Use as title field` checkbox | Select this checkbox         |

We'll click `Add` to save.

Next, we want our footer CTA section to have an image in it, so we'll add an `Asset picker` field, using the following information:

| Tab      | Field        | Input                       |
| -------- | ------------ | --------------------------- |
| Settings | Display Name | Footer image                |
| Settings | API ID       | footerImage                 |
| Settings | Description  | Add an image to your footer |

We'll click `Add` to save. In this case we're not allowing multiple values because we only want to add one image to our footer. We are also not making it a required field, because we want this image to be optional.

Next, we'll add a `Slug` field from the right sidebar, which will allow us to later on include a contact URL.

We'll use the following information:

| Tab         | Field                               | Input                                                                                                                                                                |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Contact URL                                                                                                                                                          |
| Settings    | API ID                              | contactUrl                                                                                                                                                           |
| Settings    | Description                         | Add your contact link here                                                                                                                                           |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                         |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                         |
| Validations | `Match a specific pattern` checkbox | Select this checkbox, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

That was it for the CTA section of our footer. Next, we want to be able to add links, to both internal & external pages, and our socials.

Let's add the links first. We will add a basic component field to nest the navigation item component we created earlier into our footer component. We'll use the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Links                                           |
| Settings | API ID                           | links                                           |
| Settings | `Allow multiple values` checkbox | Select this checkbox                            |
| Settings | Select component                 | Use the dropdown to select the "Navigation item" component |

We'll click `Add` to save. In this case, we've allowed multiple values, because that way we can add as many links as we want to our footer.

Finally, we will add a `Reference` field from the right sidebar, so we can use it to relate content entries to our socials. We'll use the following information:

| Tab                 | Field                        | Input                                             |
| ------------------- | ---------------------------- | ------------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced`    |
| Define              | Models to reference          | Use the dropdown menu to select `Socials`         |
| Define              | Reference direction          | Select `One-way reference`                        |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Socials per Footer links` |
| Configure reference | Display Name                 | Socials                                           |
| Configure reference | API ID                       | socials                                           |

We'll click `Add` to save.

This is how you create a simple footer component containing a simple CTA and links. Creating the footer as a component, allows you to reuse the structure in different models in your project as if it were a template!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a footer using Hygraph.  If you want to try out more section configurations, we have other [header & footer types](/docs/recipes/headers-and-footers/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Footer with sections

Source: https://hygraph.com/docs/recipes/headers-and-footers/footer-sections

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a sectioned footer component that references internal content.

This footer has three columns as sections: one for stores, one for social network links, and another for FAQ.

![Footer component with fields](/images/docs/recipes/headers-and-footers/footer-sections.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/headers-and-footers/footer-sections#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create the headers & footers, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/headers-and-footers/footer-sections#clone-the-complete-cookbook) This is the way to go if you're curious about how the headers & footers are made but don't want to follow the step-by-step creation process. This project contains the entire **Headers & footers Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this footer to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models and adding fields, reusable components, and sidebar widgets to them, as well as integrating remote sources and establishing relationships with other models.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/headers-and-footers/footer-sections#step-by-step-guide) Use this guide to create a sectioned footer component that you can use in your project.
- [Path 2:](/docs/recipes/headers-and-footers/footer-sections#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the headers & footers right away, or you can clone the project that contains the entire **Headers & footers cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to create your headers & footers, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/b0e53354c48646f6ac6c32b02a2c2f2b?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/headers-and-footers/footer-sections#4-create-the-footer).

### Clone the complete cookbook

We have prepared a project that contains the entire **Headers & footers cookbook**:

<Button
  href="https://app.hygraph.com/clone/05309f493150431d9b943111f1db3c5f?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create headers & footers, so you can compare the different field configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Sectioned footer"** component.

## Step-by-step guide

In this guide, we will create a footer component with a nested component field for links. Before we can build our footer component, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create the shop model:** We will create a sample Shop model to use in our internal links.
2. **Create the Socials model:** We will create a model that will allow us to create content entries with links ot our social network accounts.
3. **Create the FAQ model & component:** We will create an FAQ list model & and FAQ component to add to our footer.
4. **Create the footer component:** We will create a footer component that you can later add as component field to your models.

### 1. Create the shop model

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to this step](/docs/recipes/headers-and-footers/footer-sections#4-create-the-footer) to continue the tutorial.

</Alert>

![Shop model](/images/docs/recipes/headers-and-footers/shop-model.png)

One of our footer sections will display a list of shops. We will create a **Shop** model that we will later link to our footer component through a relation. 

In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create our links component!

### 2. Create the Socials model

![Socials model](/images/docs/recipes/headers-and-footers/socials-model.png)

We will create a **Socials** model that will allow us to create different social network link content entries that we can later on add to our footer as relations.

In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input    |
| ------------- | -------- |
| Display Name  | Socials  |
| API ID        | Socials  |
| API ID Plural | Socialss |

We'll click `Add model` to save, and start adding fields to this model.

We'll start with the social network name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                            |
| -------- | ----------------------------- | -------------------------------- |
| Settings | Display Name                  | Social network name              |
| Settings | API ID                        | socialNetworkName                |
| Settings | Description                   | Add the social network name here |
| Settings | `Use as title field` checkbox | Leave this checkbox selected     |

We'll click `Add` to save.

Next, we'll add a `Slug` field from the right sidebar, which will allow us to later on include URLs to link to our socials.

We'll use the following information:

| Tab         | Field                               | Input                                                                                                                                                                |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Social network URL                                                                                                                                                   |
| Settings    | API ID                              | socialNetworkUrl                                                                                                                                                     |
| Settings    | Description                         | Add the social network URL here                                                                                                                                      |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                         |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                         |
| Validations | `Match a specific pattern` checkbox | Select this checkbox, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field from the right sidebar, so we can include the social network icon as well.

We'll use the following information:

| Tab      | Field        | Input                            |
| -------- | ------------ | -------------------------------- |
| Settings | Display Name | Social network icon              |
| Settings | API ID       | socialNetworkIcon                |
| Settings | Description  | Add the social network icon here |

We'll click `Add` to save. We did not allow multiple values in this case, because we want to only be able to have one icon per social account.

### 3. Create the FAQ model & component

![FAQ model](/images/docs/recipes/headers-and-footers/faq-model.png)

We will create a **FAQ list** model that will allow us to create different sets of questions and answers.

<Alert theme="info" title="Why a model & a component?">

Let's think about the difference between components and references. You can think of components as field configuration templates, without content attached to them. While with references you are able to link to existing content entries in your project, when using components you need to add new content each time.

We often think about how they are different in order to choose when to use one or the other, but this case is a good example of how your project can benefit from combining them.

We chose to create the FAQ list schema element as a model because in a use case like this, we want to create question & answer pairs as content entries that can be easily referenced in other models later on. Then, we created the FAQ component with a reference field that connects the FAQ list model, because components can be added to other models as blocks.

It would have also been possible to skip creating the component and simply adding a reference field to the models that need FAQs, but we chose to do it this way to show an example of how you can combine components and references, and because this recipe is part of some of our [page section recipes](/docs/recipes/page-sections/section-index) where FAQ is treated a as section added as part of a modular component field rather than a relation.

</Alert>

In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input    |
| ------------- | -------- |
| Display Name  | FAQ list |
| API ID        | FaqList  |
| API ID Plural | FaqLists |

We'll click `Add model` to save, and start adding fields to this model.

We'll start with a `Single line text` field, which will be the space to write the questions. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                            |
| -------- | ----------------------------- | -------------------------------- |
| Settings | Display Name                  | Question                         |
| Settings | API ID                        | question                         |
| Settings | Description                   | You can write your question here |
| Settings | `Use as title field` checkbox | Leave this checkbox selected     |

We'll click `Add` to save.

Next, we'll ad a `Rich text` field from the right sidebar, which will be the space to write the answer to the question that we enter in the previous field.

We'll use the following information:

| Tab      | Field        | Input |
| -------- | ------------ | ----- |
| Settings | Display Name | Answer  |
| Settings | API ID       | answer  |

We'll click `Add` to save.

Now that we've created the model, we'll create a FAQ component that will allow us to select FAQ questions & answer pairs to add to our footer as a list.

To build this, we'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | FAQ   |
| API ID        | Faq   |
| API ID Plural | Faqs  |

We'll click `Add component` to save. The final step, is to add a relation as an instance inside this component.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                 | Field                        | Input                                          |
| ------------------- | ---------------------------- | ---------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced` |
| Define              | Models to reference          | Use the dropdown menu to select `FAQ list`     |
| Define              | Reference direction          | Select `One-way reference`                     |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple FAQ list per FAQ`      |
| Configure reference | Display Name                 | FAQ list                                       |
| Configure reference | API ID                       | faqList                                        |
| Configure reference | Description                  | Add question & answer sets from the FAQ list   |

We'll click `Add` to save.

### 4. Create the footer

<VideoEmbed videoId="usMhk9_ZWho" />

Now that we have all the schema elements that, both directly and indirectly, will be a part of our final footer component, we'll go ahead and create it!

![Footer component with fields](/images/docs/recipes/headers-and-footers/footer-sections.png)

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input            |
| ------------- | ---------------- |
| Display Name  | Sectioned footer |
| API ID        | SectionedFooter  |
| API ID Plural | SectionedFooters |

We'll click `Add component` to save, and then we'll start adding instances to it.

We want our footer to to have three columns, one for shops, one for our socials, and one for FAQ.

We'll start with the shops column. Let's add a `Single line text` field, which will be our column title. Let's add it by clicking `Add` on the `Single line text field` card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                                                                                 |
| -------- | ----------------------------- | ------------------------------------------------------------------------------------- |
| Settings | Display Name                  | Column 1 title                                                                        |
| Settings | API ID                        | column1Title                                                                          |
| Settings | Description                   | This is the title for the Locations column on the footer. You cannot edit this title. |
| Settings | `Use as title field` checkbox | Select this checkbox                                                                  |
| Advanced | `Set initial value` checkbox  | and write "Our locations" in the `Initial value` input.                               |
| Advanced | Field visibility              | Use the dropdown to select `Read only`                                                |

We'll click `Add` to save. This configuration creates a read-only field in our content entry that will have the title we specified. This will ensure that our footers have the same titles, even when editors can pick what content goes in them.

Next, we want to add our shops here as a relation, so we'll add a `Reference field` field, using the following information:

| Tab                 | Field                        | Input                                              |
| ------------------- | ---------------------------- | -------------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced`     |
| Define              | Models to reference          | Use the dropdown menu to select `Shop`             |
| Define              | Reference direction          | Select `One-way reference`                         |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Shop per Sectioned footer` |
| Configure reference | Display Name                 | Column 1 links                                     |
| Configure reference | API ID                       | column1Links                                       |

We'll click `Add` to save.

The next column will contain our socials. Let's add a `Single line text` field, using the following information:

| Tab      | Field                        | Input                                                                               |
| -------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| Settings | Display Name                 | Column 2 title                                                                      |
| Settings | API ID                       | column2Title                                                                        |
| Settings | Description                  | This is the title for the Socials column on the footer. You cannot edit this title. |
| Advanced | `Set initial value` checkbox | and write "Our Socials" in the `Initial value` input.                               |
| Advanced | Field visibility             | Use the dropdown to select `Read only`                                              |

We'll click `Add` to save. Just like before, this configuration creates a read-only field in our content entry that will have the title we specified. 

Next, we want to add our socials here as a relation, so we'll add a `Reference field` field, using the following information:

| Tab                 | Field                        | Input                                                 |
| ------------------- | ---------------------------- | ----------------------------------------------------- |
| Define              | Reference type               | Select `Allow only one model to be referenced`        |
| Define              | Models to reference          | Use the dropdown menu to select `Socials`             |
| Define              | Reference direction          | Select `One-way reference`                            |
| Define              | `Allow multiple...` checkbox | Select  `Allow multiple Socials per Sectioned footer` |
| Configure reference | Display Name                 | Column 2 links                                        |
| Configure reference | API ID                       | column2Links                                          |

We'll click `Add` to save.

The final column will contain our FAQ list. Let's add a `Single line text` field, using the following information:

We'll use the following information:

| Tab      | Field                        | Input                                                                           |
| -------- | ---------------------------- | ------------------------------------------------------------------------------- |
| Settings | Display Name                 | Column 3 title                                                                  |
| Settings | API ID                       | column3Title                                                                    |
| Settings | Description                  | This is the title for the FAQ column on the footer. You cannot edit this title. |
| Advanced | `Set initial value` checkbox | and write "FAQ" in the `Initial value` input.                                   |
| Advanced | Field visibility             | Use the dropdown to select `Read only`                                          |

We'll click `Add` to save. 

Next, we want to add our FAQ question & answer pairs here as a `Basic component field`, using the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Column 3 links                                  |
| Settings | API ID                           | column3Links                                    |
| Settings | Select component                 | Use the dropdown to select the "FAQ" component  |

We'll click `Add` to save. In this case, we did not allow multiple values, because the FAQ component already contains a reference field that allows multiple values. So, we can already add as many questions & answer pairs as we want to our footer.

This is how you create a sectioned footer component that references internal content in different ways.

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a sectioned footer using Hygraph.  If you want to try out more section configurations, we have other [header & footer types](/docs/recipes/headers-and-footers/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Header with links

Source: https://hygraph.com/docs/recipes/headers-and-footers/header-links

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a header component containing a title, an image and a nested component for links.

It will allow you to create a typical single-line header that contains a company logo, and multiple links to both internal and external resources.

![Header component with fields](/images/docs/recipes/headers-and-footers/header-links.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/headers-and-footers/header-links#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create the headers & footers, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/headers-and-footers/header-links#clone-the-complete-cookbook) This is the way to go if you're curious about how the headers & footers are made but don't want to follow the step-by-step creation process. This project contains the entire **Headers & footers Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this header to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models and adding fields, reusable components, and sidebar widgets to them, as well as integrating remote sources and establishing relationships with other models.

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/headers-and-footers/header-links#step-by-step-guide) Use this guide to create a header component with links that you can use in your project.
- [Path 2:](/docs/recipes/headers-and-footers/header-links#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the headers & footers right away, or you can clone the project that contains the entire **Headers & footers cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to create your headers & footers, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/b0e53354c48646f6ac6c32b02a2c2f2b?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/headers-and-footers/header-links#3-create-the-header).

### Clone the complete cookbook

We have prepared a project that contains the entire **Headers & footers cookbook**:

<Button
  href="https://app.hygraph.com/clone/05309f493150431d9b943111f1db3c5f?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create headers & footers, so you can compare the different field configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Header links"** component.

## Step-by-step guide

In this guide, we will create a header component with a nested component field for links. Before we can build our header component, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create the referenced models:** We will create 3 sample models - Author, Book, and Shop - to use in our internal links.
2. **Create the navigation item component:** We will build a navigation item component that we can nest into our header component.
3. **Create the header component:** We will create a header component that you can later add as component field to your models.

### 1. Create the basic models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to the final section](/docs/recipes/headers-and-footers/header-links#3-create-the-header) to continue the tutorial.

</Alert>

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/headers-and-footers/author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/headers-and-footers/book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/headers-and-footers/shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create our links component!

### 2. Create the navigation item component

![Create a navigation item component](/images/docs/recipes/headers-and-footers/navigation-item-component.png)

We want our header to contain a navigation item component that will allow us to add multiple links - both internal and external - to our header. To build this, we'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input           |
| ------------- | --------------- |
| Display Name  | Navigation item |
| API ID        | NavigationItem  |
| API ID Plural | NavigationItems |

We'll click `Add component` to save. It's time to start adding instances to this component.

First, we'll add a `Single line text` field by clicking on it on the **Add fields** right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                |
| -------- | ----------------------------- | -------------------- |
| Settings | Display Name                  | Link label           |
| Settings | API ID                        | linkLabel            |
| Settings | `Use as title field` checkbox | Select this checkbox |

We'll click `Add` to save.

We want our header to offer the possibility to add both internal and external links. To do this, we'll add a reference for the internal links, and a slug field for the external ones. In this case, we won't be making them required fields, because users will either use one or the other.

We'll start with the reference field. We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                | Input                                                              |
| ------------------- | -------------------- | ------------------------------------------------------------------ |
| Define              | Reference type       | Select `Allow multiple models to be referenced (Union Type)`       |
| Define              | Models to reference  | Use the dropdown menu to select `Author`, `Book` and `Shop`        |
| Define              | Reference direction  | Select `One-way reference`                                         |
| Define              | Relation cardinality | Select  `One to One`                                               |
| Configure reference | Display Name         | Internal link                                                      |
| Configure reference | API ID               | internalLink                                                       |

We'll click `Add` to save. We've configured the reference in such a way that when we find this field in a content entry, it will allow us to select an entry from the models that we selected.

Next, we'll add a `slug` field for our external URLs, using the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External URL                                                                                                                                                                 |
| Settings    | API ID                              | externalUrl                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

Finally, we want to have a boolean field that we can then toggle to indicate if a link should open on a separate tab or not.

We'll add a `boolean` field using the following information:

| Tab      | Field        | Input           |
| -------- | ------------ | --------------- |
| Settings | Display Name | New tab |
| Settings | API ID       | newTab   |

We'll click `Add` to save. 

### 3. Create the header

<VideoEmbed videoId="QfOLIOkjtVc" />

Now that we have all the schema elements that, both directly and indirectly, will be a part of our final header component, we'll go ahead and create it.

![Header component with fields](/images/docs/recipes/headers-and-footers/header-links.png)

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input        |
| ------------- | ------------ |
| Display Name  | Header links |
| API ID        | HeaderLinks  |
| API ID Plural | HeaderLinkss |

We'll click `Add component` to save, and then we'll start adding instances to it.

First, we'll add a `Single line text` field, which will be our header title. Let's add it by clicking `Add` on the `Single line text field` card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                                   |
| -------- | ----------------------------- | --------------------------------------- |
| Settings | Display Name                  | Header title                            |
| Settings | API ID                        | headerTitle                             |
| Settings | Description                   | You can add a title to your header here |
| Settings | `Use as title field` checkbox | Select this checkbox                    |

We'll click `Add` to save.

Next, we want our header to have the company logo in it, so we'll add an `Asset picker` field, using the following information:

| Tab      | Field        | Input |
| -------- | ------------ | ----- |
| Settings | Display Name | Logo  |
| Settings | API ID       | logo  |

We'll click `Add` to save. In this case we're not allowing multiple values because we only want to add one image to our headers.

Finally, we will add a basic component field to nest the navigation item component we created earlier into our header component. We'll use the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Links                                           |
| Settings | API ID                           | links                                           |
| Settings | `Allow multiple values` checkbox | Select this checkbox                            |
| Settings | Select component                 | Use the dropdown to select the "Navigation item" component |

We'll click `Add` to save. In this case, we've allowed multiple values, because that way we can add as many links as we want to our header.

This is how you create a simple header component containing a title, an image and links. Creating the header as a component, allows you to reuse the structure in different models in your project.

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a header using Hygraph.  If you want to try out more section configurations, we have other [header & footer types](/docs/recipes/headers-and-footers/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Header with notification

Source: https://hygraph.com/docs/recipes/headers-and-footers/header-notification

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create a header component with a notifications line at the top

This is ideal for websites where you need to add an additional line to the header to inform users of updates or promotions.

![Header component with fields](/images/docs/recipes/headers-and-footers/header-notification-component.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/headers-and-footers/header-notification#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create the headers & footers, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/headers-and-footers/header-notification#clone-the-complete-cookbook) This is the way to go if you're curious about how the headers & footers are made but don't want to follow the step-by-step creation process. This project contains the entire **Headers & footers Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this header to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models and adding fields, reusable components, and sidebar widgets to them, as well as integrating remote sources and establishing relationships with other models.

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/headers-and-footers/header-links#step-by-step-guide) Use this guide to create a header component with notification that you can use in your project.
- [Path 2:](/docs/recipes/headers-and-footers/header-links#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the headers & footers right away, or you can clone the project that contains the entire **Headers & footers cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to create your headers & footers, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/b0e53354c48646f6ac6c32b02a2c2f2b?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/headers-and-footers/header-notification#4-create-the-header).

### Clone the complete cookbook

We have prepared a project that contains the entire **Headers & footers cookbook**:

<Button
  href="https://app.hygraph.com/clone/05309f493150431d9b943111f1db3c5f?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create headers & footers, so you can compare the different field configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Header with notification"** component.

## Step-by-step guide

In this guide, we will create a header component with a nested component field for links. Before we can build our header component, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create the referenced models:** We will create 3 sample models - Author, Book, and Shop - to use in our internal links.
2. **Create the navigation item component:** We will build a navigation item component that we can nest into our header component.
3. **Create the Notification model:** We will create a **Notification** model that will allows us to create notifications as content entries.
4. **Create the header component:** We will create a header component that you can later add as component field to your models.

### 1. Create the basic models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/headers-and-footers/header-links#2-create-the-navigation-item-component) to continue the tutorial.

</Alert>

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/headers-and-footers/author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/headers-and-footers/book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/headers-and-footers/shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create our links component!

### 2. Create the navigation item component

![Create a navigation item component](/images/docs/recipes/headers-and-footers/navigation-item-component.png)

We want our header to contain a navigation item component that will allow us to add multiple links - both internal and external - to our header. To build this, we'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input           |
| ------------- | --------------- |
| Display Name  | Navigation item |
| API ID        | NavigationItem  |
| API ID Plural | NavigationItems |

We'll click `Add component` to save. It's time to start adding instances to this component.

First, we'll add a `Single line text` field by clicking on it on the **Add fields** right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                |
| -------- | ----------------------------- | -------------------- |
| Settings | Display Name                  | Link label           |
| Settings | API ID                        | linkLabel            |
| Settings | `Use as title field` checkbox | Select this checkbox |

We'll click `Add` to save.

We want our header to offer the possibility to add both internal and external links. To do this, we'll add a reference for the internal links, and a slug field for the external ones. In this case, we won't be making them required fields, because users will either use one or the other.

We'll start with the reference field. We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                | Input                                                              |
| ------------------- | -------------------- | ------------------------------------------------------------------ |
| Define              | Reference type       | Select `Allow multiple models to be referenced (Union Type)`       |
| Define              | Models to reference  | Use the dropdown menu to select `Product`, `Blog` and `Store` |
| Define              | Reference direction  | Select `One-way reference`                                         |
| Define              | Relation cardinality | Select  `One to One`                                               |
| Configure reference | Display Name         | Page                                                               |
| Configure reference | API ID               | page                                                               |

We'll click `Add` to save. We've configured the reference in such a way that when we find this field in a content entry, it will allow us to select an entry from the models that we selected.

Next, we'll add a `slug` field for our external URLs, using the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External URL                                                                                                                                                                 |
| Settings    | API ID                              | externalUrl                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

We'll click `Add` to save.

Finally, we want to have a boolean field that we can then toggle to indicate if a link should open on a separate tab or not.

We'll add a `boolean` field using the following information:

| Tab      | Field        | Input           |
| -------- | ------------ | --------------- |
| Settings | Display Name | New tab |
| Settings | API ID       | newTab   |

We'll click `Add` to save. 

### 3. Create the Notification model

![Notification model](/images/docs/recipes/headers-and-footers/notification-model.png)

We will create a **Notification** model that will allow us to create different notification content entries that we can later on add to our header as relations.

<Alert theme="info" title="Why a model and not a component?">

We chose to create the notification schema element as a model and not a component because in a use case like this, we have the intention of reusing content rather than a specific configuration of schema elements.

Let's think about the difference between components and references. You can think of components as field configuration templates, without content attached to them. While with references you are able to link to existing content entries in your project, when using components you need to add new content each time.

It would make sense for notifications to be repeated in different pages in your project, or even switched at different times. By creating **Notifications** as a model, we ensure that each notification content entry, can be easily referenced wherever needed in your project.

</Alert>

In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input         |
| ------------- | ------------- |
| Display Name  | Notification  |
| API ID        | Notification  |
| API ID Plural | Notifications |

We'll click `Add model` to save.

Let's add fields to this model. We'll start with the notification one-liner, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                                       |
| -------- | ----------------------------- | ------------------------------------------- |
| Settings | Display Name                  | One-line message                            |
| Settings | API ID                        | oneLineMessage                              |
| Settings | Description                   | Add your one-line notification message here |
| Settings | `Use as title field` checkbox | Leave this checkbox selected                |

We'll click `Add` to save.

We want our notification to bring attention to other parts of our content, so we'll add the navigation item component that we created earlier here.

We will add a basic component field using the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Links                                           |
| Settings | API ID                           | links                                           |
| Settings | Description                      | Add one or more links here                      |
| Settings | `Allow multiple values` checkbox | Select this checkbox                            |
| Settings | Select component                 | Use the dropdown to select the "Navigation item" component |

We'll click `Add` to save. In this case, we've allowed multiple values, because that way we can add one or more links to our notification.

Now that we have created all the schema elements that we needed for our header, let's jump into the final step!

### 4. Create the header

<VideoEmbed videoId="04-j1pD5VFo" />

Let's create our "header with notification" component. We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input                     |
| ------------- | ------------------------- |
| Display Name  | Header with notification  |
| API ID        | Header with notification  |
| API ID Plural | Header with notifications |

We'll click `Add component` to save, and then we'll start adding instances to it.

![Header component with fields](/images/docs/recipes/headers-and-footers/header-notification-component.png)

First, we'll add a `Reference` field so that we can relate a notification to our header. Let's add it by clicking `Add` on the `Reference` field card on the right sidebar.

We'll use the following information:

| Tab                 | Field               | Input                                                     |
| ------------------- | ------------------- | --------------------------------------------------------- |
| Define              | Reference type      | Select `Allow only one model to be referenced`            |
| Define              | Models to reference | Use the dropdown menu to select `Notification`            |
| Define              | Reference direction | Select `One-way reference`                                |
| Configure reference | Display Name        | Notifications                                             |
| Configure reference | API ID              | notifications                                             |
| Configure reference | Description         | Select a notification to appear at the top of your banner |

We'll click `Add` to save.

Next, we want the possibility to add an image to our header so we can show our company logo in it. To achieve this, we'll add an `Asset picker` field, using the following information:

| Tab      | Field        | Input |
| -------- | ------------ | ----- |
| Settings | Display Name | Logo  |
| Settings | API ID       | logo  |

We'll click `Add` to save. In this case we're not allowing multiple values because we only want to add one logo to our headers.

Finally, we will add a basic component field to nest the links component we created earlier into our header component. We'll use the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Links                                           |
| Settings | API ID                           | links                                           |
| Settings | Description                      | Add your header links here                      |
| Settings | `Allow multiple values` checkbox | Select this checkbox                            |
| Settings | Select component                 | Use the dropdown to select the "Navigation item" component |

We'll click `Add` to save. In this case, we've allowed multiple values, because that way we can add as many links as we need to our header.

This is how you create a simple header component containing a notifications line at the top. Creating the header as a component allows you to reuse the structure in different models in your project as if it were a template.

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a header using Hygraph.  If you want to try out more section configurations, we have other [header & footer types](/docs/recipes/headers-and-footers/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Headers & footers overview

Source: https://hygraph.com/docs/recipes/headers-and-footers/section-index

## Overview

In this section, you will find recipes that you can use to create **headers and footers** using different field configurations.

| Recipe                                                                             | Description                                                       |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [Footer with links](/docs/recipes/headers-and-footers/footer-links/)               | Learn how to create a footer with links                           |
| [Footer with sections](/docs/recipes/headers-and-footers/footer-sections/)         | Learn how to create a footer with columns as sections             |
| [Header with links](/docs/recipes/headers-and-footers/header-links/)               | Learn how to create a header with links                           |
| [Header with notification](/docs/recipes/headers-and-footers/header-notification/) | Learn how to create a header with a notifications line at the top |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Headers & footers cookbook

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to create your headers & footers, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/b0e53354c48646f6ac6c32b02a2c2f2b?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this cookbook's tutorials, and start from the final step in each recipe.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to create your headers & footers, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/b0e53354c48646f6ac6c32b02a2c2f2b?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of these tutorials, and start from the final step in each recipe.

### Clone the complete cookbook

We have prepared a project that contains the entire **Headers & footers cookbook**:

<Button
  href="https://app.hygraph.com/clone/05309f493150431d9b943111f1db3c5f?name=Hygraph%20recipes%20-%20Headers%20%26%20Footers"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create headers & footers, so you can compare the different field configurations without having to clone multiple projects.

---
# Formatted gallery section

Source: https://hygraph.com/docs/recipes/image-gallery/formatted-gallery-section

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build an image gallery component with format dropdowns and columns.

This image gallery uses assets in your Hygraph project and allows you to add as many images as you need. It also lets you select the number of columns the gallery will use to display the images, and has dropdowns for image size and aspect ratio.

![Formatted gallery section component with fields](/images/docs/recipes/image-gallery/formatted-gallery-component.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the entire cookbook.](/docs/recipes/image-gallery/formatted-gallery-section#clone-project) This is the way to go if you're curious about how the galleries are made but don't want to follow the step-by-step creation process. This project contains the entire **Image galleries Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this image gallery to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/image-gallery/formatted-gallery-section#step-by-step-guide) Use this guide to create a formatted image gallery component that you can use in your project.
- [Path 2:](/docs/recipes/image-gallery/formatted-gallery-section#clone-project) Clone the project that we created for you. It contains the entire **Image galleries cookbook** to compare the different gallery configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Image galleries cookbook**:

<Button
  href="https://app.hygraph.com/clone/c78b4279164e4195937d3e890397c65b?name=Hygraph%20Recipes%20-%20Image%20galleries"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create image galleries, so you can compare the different gallery configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Formatted galery secton"** component.

## Step-by-step guide

In this guide, we will create an image gallery component with columns and format dropdowns.

We will divide this process in steps to make it more manageable:

1. **Create the enumerations:** We will create 2 enumerations that will later help us format our galleries; one for image size and another for aspect ratio.
2. **Create the gallery component:** We will create an image gallery component that you can later add as component field to your models.

<VideoEmbed videoId="8THGK2wMOdM" />

### 1. Create the enumerations

We want our image gallery to have dropdowns that will let us select the image aspect ratio and size.

We'll start by creating the enumeration for aspect ratio. We'll click `+ Add` next to **Enumerations** and use the following information:

| Field        | Input        |
| ------------ | ------------ |
| Display Name | Aspect ratio |
| API ID       | AspectRatio  |

Next, we need to add enumeration values. These are the options we will get when using this later on as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name    | API ID        |
| --------------- | ------------- |
| Original        | original      |
| Four by three   | fourByThree   |
| Sixteen by nine | sixteenByNine |
| Three by two    | threeByTwo    |
| Square          | square        |

We'll click `Add enumeration` to save.

Next, we need to create an enumeration for image size selection. We'll repeat the process using the following information:

| Field        | Input      |
| ------------ | ---------- |
| Display Name | Image size |
| API ID       | ImageSize  |

Once more, we need to add enumeration values. For this example, we'll use four size options - full size, large, medium and small.

We'll add the following:

| Display name | API ID   |
| ------------ | -------- |
| Full size    | fullSize |
| Large        | large    |
| Medium       | medium   |
| Small        | small    |

We'll click `Add enumeration` to save.

In the next step, we will create our image gallery component and include them as enumeration fields.

### 2. Create the gallery

Now that we have the two enumerations that will be a part of our final gallery component, we'll go ahead and create it.

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input                     |
| ------------- | ------------------------- |
| Display Name  | Formatted gallery section |
| API ID        | FormattedGallerySection   |
| API ID Plural | FormattedGallerySections  |

We'll click `Add component` to save, and then we'll start adding instances to it.

We'll start with a `Single line text` field, which will be our gallery section title. Let's add it by clicking `Add` on the `Single line text` field card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                 |
| -------- | ----------------------------- | --------------------- |
| Settings | Display Name                  | Gallery section title |
| Settings | API ID                        | gallerySectionTitle   |
| Settings | Description                   | Add a title here      |
| Settings | `Use as title field` checkbox | Select this checkbox  |

We'll click `Add` to save.

Next, we want the possibility to add multiple images to our gallery, so we'll add an `Asset picker` field that allows multiple values, using the following information:

| Tab      | Field         | Input                                       |
| -------- | ------------- | ------------------------------------------- |
| Settings | Display Name  | Images                                      |
| Settings | API ID        | images                                      |
| Settings | Description   | Add your images                             |
| Settings | Field options | Select the `Allow multiple assets` checkbox |

We'll click `Add` to save. 

Now its time to add the enumerations we created earlier as enumeration fields.

We'll start with the aspect ratio enumeration. We'll find the `Enumeration` field on the **Add fields** sidebar, and click `Add` on the field card.

We'll use the following information:

| Tab      | Field        | Input                                                  |
| -------- | ------------ | ------------------------------------------------------ |
| Settings | Display Name | Images aspect ratio                                    |
| Settings | API ID       | imagesAspectRatio                                      |
| Settings | Enumeration  | Select "aspect ratio" from the dropdown menu           |
| Settings | Description  | Select the aspect ratio for the images in this gallery |

We'll click `Add` to save.

We'll follow the same steps to add the image size enumeration, using the following information:

| Tab      | Field        | Input                                        |
| -------- | ------------ | -------------------------------------------- |
| Settings | Display Name | Images size                                  |
| Settings | API ID       | imagesSize                                   |
| Settings | Enumeration  | Select "Image size" from the dropdown menu   |
| Settings | Description  | Select a size for the images in this gallery |

We'll click `Add` to save.

Finally, we'll add a `Number` field, which will allow us to indicate how many columns the gallery should have. We'll find it on the **Add fields** right sidebar, click on it, and use the following information:

| Tab         | Field                        | Input                                                                                                                                                   |
| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                 | Columns                                                                                                                                                 |
| Settings    | API ID                       | columns                                                                                                                                                 |
| Validations | `Limit input range` checkbox | Use the dropdown to select `Between` and then add the values 2 and 4. In the `Custom error message` field, write "Please add a value between 2 and 4.". |
| Advanced    | `Set initial value` checkbox | Select this checkbox and set the `Initial value` field to 2.                                                                                            |

We'll click `Add` to save.

With this configuration, we ensure that the field has a default initial value, but also allows editors to write a value between 2 and 4 instead. This way, while we allow editors to input a numeric value, we also ensure that the value added falls within a range that we set.

This is how you create an image gallery component containing a title, an asset picker to add multiple images, dropdowns for format that will let you select a gallery aspect ratio as well as an image size, and a number field to set up the number of columns. Creating the gallery as a component allows you to reuse the structure in different models in your project.

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating an image gallery using Hygraph. If you want to try out more gallery configurations, we have other [image gallery types](/docs/recipes/image-gallery/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Gallery with information

Source: https://hygraph.com/docs/recipes/image-gallery/gallery-with-info

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build an image gallery model containing a basic component field that will allow you to add multiple images, each with its own title and description.

![Gallery with info model with fields](/images/docs/recipes/image-gallery/gallery-with-info-model.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the entire cookbook.](/docs/recipes/image-gallery/gallery-with-info#clone-project) This is the way to go if you're curious about how the galleries are made but don't want to follow the step-by-step creation process. This project contains the entire **Image galleries Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this image gallery to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models and adding fields, reusable components, and sidebar widgets to them, as well as integrating remote sources and establishing relationships with other models.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/image-gallery/gallery-with-info#step-by-step-guide) Use this guide to create an image gallery model where all images have a title and description.
- [Path 2:](/docs/recipes/image-gallery/gallery-with-info#clone-project) Clone the project that we created for you. It contains the entire **Image galleries cookbook** to compare the different gallery configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Image galleries cookbook**:

<Button
  href="https://app.hygraph.com/clone/c78b4279164e4195937d3e890397c65b?name=Hygraph%20Recipes%20-%20Image%20galleries"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create image galleries, so you can compare the different gallery configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Gallery with info"** model.

## Step-by-step guide

In this guide, we will create an image gallery model with a component field for image title and description.

We will divide this process in steps to make it more manageable:

1. **Create the image component:** We will create an image component that will contain images and their metadata.
2. **Create the gallery model:** We will create the gallery model and add the component we previously created to it.

<VideoEmbed videoId="DDYuaFJ9wEU" />

### 1. Create the image component

We will start by creating our image component. It should allow us to add an image along with a title and a description.

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input           |
| ------------- | --------------- |
| Display Name  | Image with info |
| API ID        | ImageWithInfo   |
| API ID Plural | ImageWithInfos  |

We'll click `Add component` to save, and then we'll start adding instances to it.

We'll start with a `Single line text` field, which will be our image component title. Let's add it by clicking `Add` on the `Single line text` field card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                     |
| -------- | ----------------------------- | ------------------------- |
| Settings | Display Name                  | Image title               |
| Settings | API ID                        | imageTitle                |
| Settings | Description                   | Add your image title here |
| Settings | `Use as title field` checkbox | Select this checkbox      |

We'll click `Add` to save.

Next, we'll add an `Asset picker` field that will let us add images, using the following information:

| Tab      | Field        | Input             |
| -------- | ------------ | ----------------- |
| Settings | Display Name | Image             |
| Settings | API ID       | image             |
| Settings | Description  | Select your image |

We'll click `Add` to save. In this case we will not allow multiple values, because we want to add a single image per title & description.

Finally, we'll add a `Multi line text` field, for our image description. We'll select it from the right sidebar, and use this information:

| Tab      | Field        | Input                    |
| -------- | ------------ | ------------------------ |
| Settings | Display Name | Image description        |
| Settings | API ID       | imageDescription         |
| Settings | Description  | Write a description here |

We'll click `Add` to save.

Now that our component is ready, let's move on to model creation.

<Alert theme="info" title="Pro Tip">

Another way to add  metadata to your images, is to add the fields directly to your Asset System model. [This guide shows you how to do it](/docs/getting-started/build-content-models#asset-model).

In this tutorial, we choose to add this information as instances to a component because this way the images in your gallery can be reused with a different title & description each time.

You can think of components as field configuration templates, without content attached to them. Unlike with references, when using components, you need to add new content each time.

Both ways of adding metadata can be a good choice; when using this in the future, think about your use case to choose the one that works best for your project!

</Alert>

### 2. Create the gallery model

Now that we have a component that lets us add an image with title and description, let's create a gallery model.

In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input             |
| ------------- | ----------------- |
| Display Name  | Gallery with info |
| API ID        | GalleryWithInfo   |
| API ID Plural | GalleryWithInfos  |

We'll click `Add model` to save.

Our model has been created but it's empty. To create our image gallery model, we'll add the gallery title, and the component we created earlier.

Let's start with the title, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Gallery title                |
| Settings | API ID                        | galleryTitle                 |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add our "image with info" component. We'll make sure the component allows multiple values, so that it lets us add multiple images with title and description to a content entry.

We'll find the `Basic component` field on the **Add fields** right sidebar, click `Add` to add it, and use the following information:

| Tab      | Field            | Input                                                      |
| -------- | ---------------- | ---------------------------------------------------------- |
| Settings | Display Name     | Image                                                      |
| Settings | API ID           | image                                                      |
| Settings | Description      | Add your images                                            |
| Settings | Field options    | Select the `Allow multiple values` checkbox                |
| Settings | Select component | Use the dropdown to select the "Image with info" component |

We'll click `Add` to save.

This is how you create an image gallery model containing a title and a component that will allow you to add multiple instances of an image with a title and description.

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating an image gallery using Hygraph. If you want to try out more gallery configurations, we have other [image gallery types](/docs/recipes/image-gallery/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Styled image gallery

Source: https://hygraph.com/docs/recipes/image-gallery/image-gallery-styled

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a simple image gallery with style dropdowns.

This image gallery uses assets in your Hygraph project and allows you to add as many images as you need. It also lets you select a gallery theme and the size of the thumbnails.

![Image gallery component with fields](/images/docs/recipes/image-gallery/image-gallery-styled.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the entire cookbook.](/docs/recipes/image-gallery/image-gallery-styled#clone-project) This is the way to go if you're curious about how the galleries are made but don't want to follow the step-by-step creation process. This project contains the entire **Image galleries Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this image gallery to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/image-gallery/image-gallery-styled#step-by-step-guide) Use this guide to create an image gallery component with with style dropdowns that you can use in your project.
- [Path 2:](/docs/recipes/image-gallery/image-gallery-styled#clone-project) Clone the project that we created for you. It contains the entire **Image galleries cookbook** to compare the different gallery configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Image galleries cookbook**:

<Button
  href="https://app.hygraph.com/clone/c78b4279164e4195937d3e890397c65b?name=Hygraph%20Recipes%20-%20Image%20galleries"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create image galleries, so you can compare the different gallery configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Styled image gallery"**.

## Step-by-step guide

In this guide, we will create an image gallery component with with theme and thumbnail size dropdowns.

We will divide this process in steps to make it more manageable:

1. **Create the enumerations:** We will create 2 enumerations that will later help us style our galleries; one for thumbnail size and another for gallery theme.
2. **Create the gallery component:** We will create an image gallery component that you can later add as component field to your models.

<VideoEmbed videoId="SBlxG0WvlIU" />

### 1. Create the enumerations

We want our image gallery to have dropdowns that will let us select theme and thumbnail size.

We'll start by creating the enumeration for theme. We'll click `+ Add` next to **Enumerations** and use the following information:

| Field        | Input |
| ------------ | ----- |
| Display Name | Theme |
| API ID       | Theme |

Next, we need to add enumeration values. These are the options we will get when using this later on as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

We'll click `Add enumeration` to save.

Next, we need to create an enumeration for thumbnail size selection. We'll repeat the process using the following information:

| Field        | Input          |
| ------------ | -------------- |
| Display Name | Thumbnail size |
| API ID       | ThumbnailSize  |

Once more, we need to add enumeration values. For this example, we'll use two size options - large and small:

| Display name | API ID |
| ------------ | ------ |
| Large        | large  |
| Small        | small  |

We'll click `Add enumeration` to save.

In the next step, we will create our image gallery component and include them as enumeration fields.

### 2. Create the gallery

Now that we have the two enumerations that will be a part of our final gallery component, we'll go ahead and create it.

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input                |
| ------------- | -------------------- |
| Display Name  | Styled image gallery |
| API ID        | StyledImageGallery   |
| API ID Plural | StyledImageGalleries |

We'll click `Add component` to save, and then we'll start adding instances to it.

First, we'll add a `Single line text` field, which will be our image gallery title. Let's add it by clicking `Add` on the `Single line text` field card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                |
| -------- | ----------------------------- | -------------------- |
| Settings | Display Name                  | Gallery title        |
| Settings | API ID                        | galleryTitle         |
| Settings | `Use as title field` checkbox | Select this checkbox |

We'll click `Add` to save.

Next, we want the possibility to add multiple images to our gallery, so we'll add an `Asset picker` field that allows multiple values, using the following information:

| Tab      | Field         | Input                                       |
| -------- | ------------- | ------------------------------------------- |
| Settings | Display Name  | Images                                      |
| Settings | API ID        | images                                      |
| Settings | Field options | Select the `Allow multiple assets` checkbox |

We'll click `Add` to save. 

Now its time to add the enumerations we created earlier as enumeration fields.

We'll start with the theme enumeration. We'll find the `Enumeration` field on the **Add fields** sidebar, and click `Add` on the field card.

We'll use the following information:

| Tab      | Field        | Input                                 |
| -------- | ------------ | ------------------------------------- |
| Settings | Display Name | Gallery theme                         |
| Settings | API ID       | galleryTheme                          |
| Settings | Enumeration  | Select "Theme" from the dropdown menu |

We'll click `Add` to save.

Finally, we'll follow the same steps to add the thumbnail size enumeration, using the following information:

| Tab      | Field        | Input                                          |
| -------- | ------------ | ---------------------------------------------- |
| Settings | Display Name | Thumbnails size                                |
| Settings | API ID       | thumbnailsSize                                 |
| Settings | Enumeration  | Select "Thumbnail size" from the dropdown menu |

We'll click `Add` to save.

This is how you create a simple image gallery component containing a title, an asset picker to add multiple images, and dropdowns for style that will let you select a gallery theme as well as a thumbnails size. Creating the gallery as a component, allows you to reuse the structure in different models in your project.

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating an image gallery using Hygraph. If you want to try out more gallery configurations, we have other [image gallery types](/docs/recipes/image-gallery/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Image galleries overview

Source: https://hygraph.com/docs/recipes/image-gallery/section-index

## Overview

In this section, you will find recipes that you can use to create **image galleries** using different field configurations.

| Recipe                                                                             | Description                                                                                                                                                       |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Formatted gallery section](/docs/recipes/image-gallery/formatted-gallery-section) | Learn how to build an image gallery component with format dropdowns and columns.                                                                                  |
| [Gallery with information](/docs/recipes/image-gallery/gallery-with-info)          | Learn how to build an image gallery model containing a basic component field that will allow you to add multiple images, each with its own title and description. |
| [Styled image gallery](/docs/recipes/image-gallery/image-gallery-styled)           | Learn how to build a simple image gallery with style dropdowns.                                                                                                   |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Image galleries cookbook

We have prepared a project that contains the entire **Image galleries cookbook**:

<Button
  href="https://app.hygraph.com/clone/c78b4279164e4195937d3e890397c65b?name=Hygraph%20Recipes%20-%20Image%20galleries"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create image galleries, so you can compare the different gallery configurations without having to clone multiple projects.


---
# Hygraph recipes

Source: https://hygraph.com/docs/recipes/index

## Overview

**Hygraph Recipes** is a collection of developer resources that can help you discover how to combine different field types to create schema elements.

You will find documentation sections - which we are calling **Cookbooks** - based on real-life use cases. Each cookbook contains a number of guides - or **Recipes**! - that show different ways of creating an element type.

You can use this content to learn how to work with Hygraph and discover what you can do with it, or clone projects that already contain schema elements to save yourself time!

**Each recipe offers 2 paths:**
- A step-by-step guide, in case you want to build these elements from scratch.
- A clonable cookbook project containing several recipes, in case you want to compare the different ways to build a schema element.

<Alert theme="info" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Highlights

<CardGrid columns='2' gap='sm' className="!px-0">
  <ListComparisonCard
    title="Banners"
    items={[
      <Link className="text-neutral" href="/docs/recipes/banners/banner-references">References banner</Link>,
      <Link className="text-neutral" href="/docs/recipes/banners/banner-slider">Banner slider</Link>,
      <Link className="text-neutral" href="/docs/recipes/banners/banner-image">Image banner</Link>
    ]}
  />
  <ListComparisonCard
    title="Buttons"
    items={[
      <Link className="text-neutral" href="/docs/recipes/buttons/button-simple">Simple button</Link>,
      <Link className="text-neutral" href="/docs/recipes/buttons/button-socials">Social links</Link>,
      <Link className="text-neutral" href="/docs/recipes/buttons/button-link-styled">Styled button link</Link>
    ]}
  />
  <ListComparisonCard
    title="Card Grid"
    items={[
      <Link className="text-neutral" href="/docs/recipes/card-grid/card-grid-components">Card grid with components</Link>,
      <Link className="text-neutral" href="/docs/recipes/card-grid/card-grid-references">Card grid with references</Link>
    ]}
  />
  <ListComparisonCard
    title="CTA"
    items={[
      <Link className="text-neutral" href="/docs/recipes/cta/cta-simple">Simple CTA</Link>,
      <Link className="text-neutral" href="/docs/recipes/cta/cta-socials">CTA with socials</Link>,
      <Link className="text-neutral" href="/docs/recipes/cta/cta-styled">Styled CTA</Link>
    ]}
  />
  <ListComparisonCard
    title="FAQ"
    items={[
      <Link className="text-neutral" href="/docs/recipes/faq/blocks-faq-page">Blocks FAQ Page</Link>,
      <Link className="text-neutral" href="/docs/recipes/faq/conditional-faq-list">Conditional FAQ List</Link>,
      <Link className="text-neutral" href="/docs/recipes/faq/sectioned-faq-page">Sectioned FAQ Page</Link>
    ]}
  />
  <ListComparisonCard
    title="Headers & footers"
    items={[
      <Link className="text-neutral" href="/docs/recipes/headers-and-footers/footer-links">Footer with links</Link>,
      <Link className="text-neutral" href="/docs/recipes/headers-and-footers/footer-sections">Footer with sections</Link>,
      <Link className="text-neutral" href="/docs/recipes/headers-and-footers/header-notification">Header with notification</Link>
    ]}
  />
  <ListComparisonCard
    title="Image galleries"
    items={[
      <Link className="text-neutral" href="/docs/recipes/image-gallery/formatted-gallery-section">Formatted gallery section</Link>,
      <Link className="text-neutral" href="/docs/recipes/image-gallery/gallery-with-info">Gallery with information</Link>,
      <Link className="text-neutral" href="/docs/recipes/image-gallery/image-gallery-styled">Styled image gallery</Link>
    ]}
  />
  <ListComparisonCard
    title="Navigation"
    items={[
      <Link className="text-neutral" href="/docs/recipes/navigation/navigation-simple">Simple navigation</Link>,
      <Link className="text-neutral" href="/docs/recipes/navigation/navigation-styled">Styled navigation</Link>,
      <Link className="text-neutral" href="/docs/recipes/navigation/navigation-sectioned">Sectioned navigation</Link>
    ]}
  />
  <ListComparisonCard
    title="Page sections"
    items={[
      <Link className="text-neutral" href="/docs/recipes/page-sections/landing-page">Landing page</Link>,
      <Link className="text-neutral" href="/docs/recipes/page-sections/multi-purpose-section">Multi-purpose section</Link>,
      <Link className="text-neutral" href="/docs/recipes/page-sections/related-content-block">Related content block</Link>
    ]}
  />
  <ListComparisonCard
    title="Product page"
    items={[
      <Link className="text-neutral" href="/docs/recipes/product-page/product-page-ecommerce">Product Page eCommerce</Link>,
      <Link className="text-neutral" href="/docs/recipes/product-page/product-page-remote-source">Product Page with Remote Source</Link>,
      <Link className="text-neutral" href="/docs/recipes/product-page/product-pages-connected">Related Product Pages</Link>
    ]}
  />
  <ListComparisonCard
    title="Taxonomy"
    items={[
      <Link className="text-neutral" href="/docs/recipes/taxonomy/flat-taxonomy">Flat Taxonomy Model</Link>,
      <Link className="text-neutral" href="/docs/recipes/taxonomy/two-level-taxonomy">Two-level Taxonomy Model</Link>,
    ]}
  />
</CardGrid>

## Recipes list

| Cookbook          | Recipe                                                                                   | Description                                                                                                                                         |
| ----------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Banners           | [Simple banner](/docs/recipes/banners/banner-simple/)                                    | Learn how to create a simple banner                                                                                                                 |
| Banners           | [References banner](/docs/recipes/banners/banner-references/)                            | Learn how to create a banner model that allows you to easily reference content from other models                                                    |
| Banners           | [Banner slider](/docs/recipes/banners/banner-slider/)                                    | Learn how to create a banner slide where you can add multiple banners that will change on a timer                                                   |
| Banners           | [Image banner](/docs/recipes/banners/banner-image/)                                      | Learn how to create an image banner with                                                                                                            |
| Buttons           | [Simple button](/docs/recipes/buttons/button-simple/)                                    | Learn how to create a simple button                                                                                                                 |
| Buttons           | [Social links](/docs/recipes/buttons/button-socials/)                                    | Learn how to create a to link your socials                                                                                                          |
| Buttons           | [Styled button link](/docs/recipes/buttons/button-link-styled/)                          | Learn how to create a link button that uses style dropdowns                                                                                         |
| Card Grid         | [Card grid with components](/docs/recipes/card-grid/card-grid-components/)               | Learn how to create a card grid using components                                                                                                    |
| Card Grid         | [Card grid with references](/docs/recipes/card-grid/card-grid-references/)               | Learn how to create a card grid using references                                                                                                    |
| CTA               | [Simple CTA](/docs/recipes/cta/cta-simple/)                                              | Learn how to create a simple CTA                                                                                                                    |
| CTA               | [CTA with socials](/docs/recipes/cta/cta-socials/)                                       | Learn how to create a CTA with social links                                                                                                         |
| CTA               | [Styled CTA](/docs/recipes/cta/cta-styled/)                                              | Learn how to create a CTA with style dropdowns                                                                                                      |
| FAQ               | [Blocks FAQ Page](/docs/recipes/faq/blocks-faq-page)                                     | Learn how to create an FAQ Model that lets you add different sets of FAQ as blocks.                                                                 |
| FAQ               | [Conditional FAQ List](/docs/recipes/faq/conditional-faq-list)                           | Learn how to create an FAQ Model that lets you select from different tables of predefined Q&A pairs based on condition.                             |
| FAQ               | [Reference FAQ Component](/docs/recipes/faq/reference-faq-component)                     | Learn how to create an FAQ Component that lets you form a list of predefined Q&A pairs.                                                             |
| FAQ               | [Sectioned FAQ Page](/docs/recipes/faq/sectioned-faq-page)                               | Learn how to create an FAQ model that lets you add lists of topic-based Q&A lists.                                                                  |
| FAQ               | [Simple FAQ Page](/docs/recipes/faq/simple-faq-page)                                     | Learn how to create an FAQ model that lets you add a list of Q&A pairs.                                                                             |
| Headers & Footers | [Footer with links](/docs/recipes/headers-and-footers/footer-links/)                     | Learn how to create a footer with links                                                                                                             |
| Headers & Footers | [Footer with sections](/docs/recipes/headers-and-footers/footer-sections/)               | Learn how to create a footer with columns as sections                                                                                               |
| Headers & Footers | [Header with links](/docs/recipes/headers-and-footers/header-links/)                     | Learn how to create a header with links                                                                                                             |
| Headers & Footers | [Header with notification](/docs/recipes/headers-and-footers/header-notification/)       | Learn how to create a header with a notifications line at the top                                                                                   |
| Image galleries   | [Formatted gallery section](/docs/recipes/image-gallery/formatted-gallery-section)       | Learn how to create an image gallery component with format dropdowns and columns                                                                    |
| Image galleries   | [Gallery with information](/docs/recipes/image-gallery/gallery-with-info)                | Learn how to create an image gallery model with a basic component fields to add images with metadata                                                |
| Image galleries   | [Styled image gallery](/docs/recipes/image-gallery/image-gallery-styled)                 | Learn how to create an image gallery component with style                                                                                           |
| Navigation        | [Simple navigation](/docs/recipes/navigation/navigation-simple/)                         | Learn how to create a simple navigation                                                                                                             |
| Navigation        | [Styled navigation](/docs/recipes/navigation/navigation-styled/)                         | Learn how to create a navigation with style dropdowns                                                                                               |
| Navigation        | [Sectioned navigation](/docs/recipes/navigation/navigation-sectioned/)                   | Learn how to create navigation with internal sections                                                                                               |
| Page sections     | [Multi-purpose section](/docs/recipes/page-sections/multi-purpose-section)               | Learn how to create a multi-purpose section component that you can add as a block selector to different models in your schema                       |
| Page sections     | [Related content block](/docs/recipes/page-sections/related-content-block)               | Learn how to create a related content block component containing a title, a body, an image, and a reference                                         |
| Page sections     | [Landing page](/docs/recipes/page-sections/landing-page)                                 | Learn how to create a dynamic landing page model that will allow you to create different landing page configurations                                |
| Product Page      | [Product Page eCommerce](/docs/recipes/product-page/product-page-ecommerce)              | Learn how to create a Product model for eCommerce with Product information stored in the CMS.                                                       |
| Product Page      | [Product Page with Akeneo app](/docs/recipes/product-page/product-page-akeneo)           | Learn how to create a Product model in Hygraph that fetches product information from an external PIM (Akeneo) via app integrations.                 |
| Product Page      | [Product Page with Remote Source](/docs/recipes/product-page/product-page-remote-source) | Learn how to create a Product model in Hygraph that fetches product information from an external PIM via Remote Sources.                            |
| Product Page      | [Related Product Pages](/docs/recipes/product-page/product-pages-connected)              | Learn how to create interconnected Product models for an online bookstore with Product information stored in the CMS.                               |
| Taxonomy          | [Flat Taxonomy model](/docs/recipes/taxonomy/flat-taxonomy)                              | Learn how to create a flat taxonomy model.                                                                                                          |
| Taxonomy          | [Two-level taxonomy model](/docs/recipes/taxonomy/two-level-taxonomy)                    | Learn how to create a two-level taxonomy model that lets you select parent categories that displays reference fields to add related sub-categories. |



---
# Sectioned navigation

Source: https://hygraph.com/docs/recipes/navigation/navigation-sectioned

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a sectioned navigation using enumerations and nested components.

Our sectioned navigation will be a content model containing an ID, nested components for sections and navigation items, and a dropdown to select styling options. This way, to create a navigation using this configuration, you can create a content entry with its own ID, and as many navigation items as you need.

This navigation model is a good choice for large projects where you need to group your navigation items into clusters or specific subjects.

![Sectioned navigation](/images/docs/recipes/navigation/navigation-sectioned.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/navigation/navigation-sectioned#clone-project) This is the way to go if you're curious about how the Navigation elements are made but don't want to follow the step-by-step creation process. This project contains the entire **Navigation Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this Navigation to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, references, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **References:** 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.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/navigation/navigation-sectioned/#step-by-step-guide) Use this guide to create a sectioned navigation that you can use in your Hygraph projects.
- [Path 2:](/docs/recipes/navigation/navigation-sectioned/#clone-project) Clone the project that contains the entire **Navigation cookbook** to compare the different navigation configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Navigation cookbook**:

<Button
  href="https://app.hygraph.com/clone/4c6eeda2afc048b39cda460d24bb1d7f?name=Hygraph%20Recipes%20-%20Navigation"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create navigation elements, so you can compare the different navigation configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Sectioned Navigation"**.

## Step-by-step guide

Before we can build our **Sectioned Navigation**, we need to create other schema elements that we can later add to it.

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create the models

We'll start by creating three sample models - Product, Store, and Blog - that we will use as referenceable models later to create our navigation items.

<Alert theme="info" title="Pro Tip">
In a real situation, you would use actual content models that you planned and built for your project, but for the sake of this example, we will simply create three empty content models so we can later on reference them.
</Alert>

We'll click `+ Add` next to **Models** and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Product |
| API ID        | Product  |
| API ID Plural | Products |

![Create the models](/images/docs/recipes/navigation/navigation-sectioned-createmodel.png)

We'll click `Add Model` to save.

Normally, we'd add fields to these models, but for the sake of this example, we'll simply leave them empty.

Repeat the process to create a second model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Blog |
| API ID        | Blog  |
| API ID Plural | Blogs |

We'll click `Add Model` to save.

And one final time for our third model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Store |
| API ID        | Store  |
| API ID Plural | Stores |

We'll click `Add Model` to save.

Finally, we will create one more model for our sectioned navigation, using the following information:

| Field         | Input                |
| ------------- | -------------------- |
| Display Name  | Sectioned navigation |
| API ID        | SectionedNavigation  |
| API ID Plural | SectionedNavigations |

We'll click `Add Model` to save. This model won't stay empty, but before we can start adding fields to it, we need to build an enumeration and a component.

### 2. Create a theme enumeration

We want our navigation to allow choosing a theme. To do this, we'll create an enumeration that we can later add to our **Navigation** model as a field.

We'll click `+ Add` next to **Enumerations** and use the following information:

| Field        | Input            |
| ------------ | ---------------- |
| Display Name | Navigation theme |
| API ID       | NavigationTheme  |

![Sectioned navigation - Theme enumeration](/images/docs/recipes/navigation/navigation-sectioned-enum-theme.png)

Next, we need to add enumeration values. These are the options we will get when using this later on as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

![Sectioned navigation - Theme values](/images/docs/recipes/navigation/navigation-sectioned-enum-themevalues.png)

We'll click `Add enumeration` to save.

### 3. Create the components

We want our navigation to have nested components. We will create a **navigation item** component that will allow us to add multiple links to our navigation. We will then nest this component into a navigation section component. The objective is to be able to add several sections with links.

The first component that we will create is the **Navigation item** component. We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input           |
| ------------- | --------------- |
| Display Name  | Navigation item |
| API ID        | NavigationItem  |
| API ID Plural | NavigationItems |

![Navigation item component](/images/docs/recipes/navigation/navigation-sectioned-component-navitem.png)

We'll click `Add component` to save. We can now start adding instances to this component. 

We'll start by adding a `Single line text` field by clicking on it on the **Add fields** right sidebar.

We'll use the following information:

| Tab         | Field                          | Input                |
| ----------- | ------------------------------ | -------------------- |
| Settings    | Display Name                   | Link label           |
| Settings    | API ID                         | linkLabel            |
| Settings    | `Use as title field` checkbox  | Select this checkbox |
| Validations | `Make field required` checkbox | Select this checkbox |

![Navigation item component - Link label](/images/docs/recipes/navigation/navigation-sectioned-component-label.png)

We'll click `Add` to save. This field will let us add a label to our links.

Next, we want our navigation to indicate if an item is new. To do this, we'll add a `boolean` field using the following information:

| Tab      | Field        | Input           |
| -------- | ------------ | --------------- |
| Settings | Display Name | New item toggle |
| Settings | API ID       | newItemToggle   |

![Navigation item component - Toggle](/images/docs/recipes/navigation/navigation-sectioned-component-toggle.png)

We'll click `Add` to save.

We want our navigation to offer the possibility to add both internal and external links. We'll add a reference for the internal links, and a slug field for the external ones. In this case, we won't be making them required fields, because users will either use one or the other.

We'll start with the reference field. We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                | Input                                                              |
| ------------------- | -------------------- | ------------------------------------------------------------------ |
| Define              | Reference type       | Select `Allow multiple models to be referenced (Union Type)`       |
| Define              | Models to reference  | Use the dropdown menu to select `Product`, `Blog` and `Store` |
| Define              | Reference direction  | Select `One-way reference`                                         |
| Define              | Relation cardinality | Select  `One to One`                                               |
| Configure reference | Display Name         | Page                                                               |
| Configure reference | API ID               | page                                                               |

![Navigation item component - Reference](/images/docs/recipes/navigation/navigation-sectioned-component-reference.png)

We'll click `Add` to save. We've configured the reference in such a way that when we find this field in a content entry, it will allow us to select an entry from the models that we configured.

Finally, we'll add a `slug` field for our external URLs, using the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External Link                                                                                                                                                                |
| Settings    | API ID                              | externalLink                                                                                                                                                                 |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Navigation item component - External URL](/images/docs/recipes/navigation/navigation-sectioned-component-url.png)

We'll click `Add` to save.

Now that we created our **Navigation item** component, we can start working on our **Navigation section** component.

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input              |
| ------------- | ------------------ |
| Display Name  | Navigation section |
| API ID        | NavigationSection  |
| API ID Plural | NavigationSections |

![Navigation section component](/images/docs/recipes/navigation/navigation-sectioned-navsection.png)

We'll click `Add component` to save. We can now start adding instances to this component.

We'll add a `Single line text` field by clicking on it on the **Add fields** right sidebar and using the following information:

| Tab         | Field                          | Input                |
| ----------- | ------------------------------ | -------------------- |
| Settings    | Display Name                   | Section title        |
| Settings    | API ID                         | sectionTitle         |
| Settings    | `Use as title field` checkbox  | Select this checkbox |
| Validations | `Make field required` checkbox | Select this checkbox |

![Navigation section component - Title](/images/docs/recipes/navigation/navigation-sectioned-navsection-title.png)

We'll click `Add` to save. This field will let us add a title to our navigation sections.

Now it is time to add the navigation item component that we created earlier. We'll click on the `Basic component` field in the **Add fields** right sidebar and use the following information:

| Tab      | Field                            | Input                                                      |
| -------- | -------------------------------- | ---------------------------------------------------------- |
| Settings | Display Name                     | Navigation items                                           |
| Settings | API ID                           | navigationItems                                            |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                       |
| Settings | Select component                 | Use the dropdown to select the "Navigation item" component |

![Navigation section component - Navigation item](/images/docs/recipes/navigation/navigation-sectioned-navsection-navitem.png)

We'll click `Add` to save.

In this case, we've allowed multiple values, because that way we can add as many links as we want to our navigation section.

### 4. Add fields to the Navigation model

We'll go back into our **Sectioned Navigation** model now, to add fields to it. The reason we're creating this navigation as a model, is so that we can then create an entry per navigation that we want to build using this configuration.

First, we will add a `slug` field that will be our navigation ID. We'll click on the `Slug` field in the **Add fields** right sidebar and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                         |
| ----------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Navigation ID                                                                                                                                                                 |
| Settings    | API ID                              | navigationId                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                  |
| Settings    | `Use as title field` checkbox       | Select this checkbox                                                                                                                                                          |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                  |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `Slug` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Sectioned navigation model - Navigation ID](/images/docs/recipes/navigation/navigation-sectioned-model-id.png)

We'll click `Add` to save.

Now it is time to add the **Navigation section** component that we created earlier. We'll click on the `Basic component` field in the **Add fields** right sidebar and use the following information:

| Tab      | Field                            | Input                                                         |
| -------- | -------------------------------- | ------------------------------------------------------------- |
| Settings | Display Name                     | Sections                                                      |
| Settings | API ID                           | sections                                                      |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                          |
| Settings | Select component                 | Use the dropdown to select the "Navigation section" component |

![Sectioned navigation model - Sections](/images/docs/recipes/navigation/navigation-sectioned-model-sections.png)

We'll click `Add` to save. In this case, we've allowed multiple values, because that way we can add as many links as we want to our navigation.

Finally, we'll add the **theme** enumeration that we created earlier. We'll find the `Enumeration` field on the **Add fields** sidebar, and add it using this information:

| Tab      | Field        | Input                                            |
| -------- | ------------ | ------------------------------------------------ |
| Settings | Display Name | Theme                                            |
| Settings | API ID       | theme                                            |
| Settings | Enumeration  | Select "Navigation theme" from the dropdown menu |

![Sectioned navigation model - Theme](/images/docs/recipes/navigation/navigation-sectioned-model-theme.png)

We'll click `Add` to save.

<Alert theme="info" title="Pro Tip">
We've created a sectioned navigation model that contains enumerations, components, as well as other schema elements, and that allows you to add internal content entries and external links.

You could potentially use this model to create different navigation elements for your project.
</Alert>

Our sectioned navigation model should look like this: 

![Sectioned navigation](/images/docs/recipes/navigation/navigation-sectioned.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our navigation recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

- [Simple navigation:](/docs/recipes/navigation/navigation-simple/) Learn how to build a simple navigation model containing menu items with basic information.
- [Styled navigation:](/docs/recipes/navigation/navigation-styled/) Learn how to build a styled navigation that lets you select styling options and use a toggle to indicate if a menu item is new.
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Simple navigation

Source: https://hygraph.com/docs/recipes/navigation/navigation-simple

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a simple navigation using a slug field and components.

Our simple navigation will be a content model containing an ID and component field that allows multiple values. This way, to create a navigation using this configuration, you can create a content entry with its own ID, and as many navigation links as you need.

Use this simple model to create a basic navigation containing labelled navigation items that can link to both internal and external documents.

![Simple navigation](/images/docs/recipes/navigation/navigation-simple.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/navigation/navigation-simple#clone-project) This is the way to go if you're curious about how the Navigation elements are made but don't want to follow the step-by-step creation process. This project contains the entire **Navigation Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this Navigation to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with references,  components and basic component fields. Let's look into these concepts:

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **References:** 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.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/navigation/navigation-simple/#step-by-step-guide) Use this guide to create a simple navigation that you can use in your Hygraph projects.
- [Path 2:](/docs/recipes/navigation/navigation-simple/#clone-project) Clone the project that contains the entire **Navigation cookbook** to compare the different navigation configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Navigation cookbook**:

<Button
  href="https://app.hygraph.com/clone/4c6eeda2afc048b39cda460d24bb1d7f?name=Hygraph%20Recipes%20-%20Navigation"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create navigation elements, so you can compare the different navigation configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Simple Navigation"**.

## Step-by-step guide

Before we can build our **Simple Navigation** model, we need to create other schema elements that we can later add to it.

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create models

We'll start by creating three sample models - Product, Store, and Blog - that we will use as referenceable models later to create our navigation items.

<Alert theme="info" title="Pro Tip">
In a real situation, you would use actual content models that you planned and built for your project, but for the sake of this example, we will simply create three empty content models so we can later on reference them.
</Alert>

We'll click `+ Add` next to **Models** and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Product |
| API ID        | Product  |
| API ID Plural | Products |

![Create models](/images/docs/recipes/navigation/navigation-simple-models.png)

We'll click `Add Model` to save.

Normally, we'd add fields to these models, but for the sake of this example, we'll simply leave them empty.

Repeat the process to create a second model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Blog |
| API ID        | Blog  |
| API ID Plural | Blogs |

We'll click `Add Model` to save.

And one final time for our third model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Store |
| API ID        | Store  |
| API ID Plural | Stores |

We'll click `Add Model` to save.

Finally, we will create one more model for our simple Navigation, using the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Simple navigation |
| API ID        | SimpleNavigation  |
| API ID Plural | SimpleNavigations |

We'll click `Add Model` to save. This model won't stay empty, but before we can add fields to it, we need to build a component.

### 2. Create a link component

We want our navigation to contain a link component that will allow us to add multiple links to our navigation. We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Link  |
| API ID        | Link  |
| API ID Plural | Links |

![Create a link component](/images/docs/recipes/navigation/navigation-simple-link-component.png)

We'll click `Add component` to save. It's time to start adding instances to this component.

First, we'll add a `Single line text` field by clicking on it on the **Add fields** right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                |
| -------- | ----------------------------- | -------------------- |
| Settings | Display Name                  | Link label           |
| Settings | API ID                        | linkLabel            |
| Settings | `Use as title field` checkbox | Select this checkbox |

![Link component - Label](/images/docs/recipes/navigation/navigation-simple-link-label.png)

We'll click `Add` to save.

We want our navigation to offer the possibility to add both internal and external links. To do this, we'll add a reference for the internal links, and a slug field for the external ones. In this case, we won't be making them required fields, because users will either use one or the other.

We'll start with the reference field. We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                | Input                                                              |
| ------------------- | -------------------- | ------------------------------------------------------------------ |
| Define              | Reference type       | Select `Allow multiple models to be referenced (Union Type)`       |
| Define              | Models to reference  | Use the dropdown menu to select `Product`, `Blog` and `Store` |
| Define              | Reference direction  | Select `One-way reference`                                         |
| Define              | Relation cardinality | Select  `One to One`                                               |
| Configure reference | Display Name         | Page                                                               |
| Configure reference | API ID               | page                                                               |

![Link component - Reference](/images/docs/recipes/navigation/navigation-simple-link-reference.png)

We'll click `Add` to save. We've configured the reference in such a way that when we find this field in a content entry, it will allow us to select an entry from the models that we selected.

Finally, we'll add a `slug` field for our external URLs, using the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External URL                                                                                                                                                                 |
| Settings    | API ID                              | externalUrl                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Link component - External URL](/images/docs/recipes/navigation/navigation-simple-link-url.png)

We'll click `Add` to save.

### 3. Add fields to the Navigation model

We'll go back into our **Simple Navigation** model now, to add fields to it. The reason we're creating this navigation as a model, is so that we can then create an entry per navigation that we want to build using this configuration.

First, we will add a `slug` field that will be our navigation ID. We'll click on the `Slug` field in the **Add fields** right sidebar and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                         |
| ----------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Navigation ID                                                                                                                                                                 |
| Settings    | API ID                              | navigationId                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                  |
| Settings    | `Use as title field` checkbox       | Select this checkbox                                                                                                                                                          |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                  |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `Slug` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Simple navigation - ID](/images/docs/recipes/navigation/navigation-simple-id.png)

We'll click `Add` to save.

Now it is time to add the link component that we created earlier. We'll click on the `Basic component` field in the **Add fields** right sidebar and use the following information:

| Tab      | Field                            | Input                                           |
| -------- | -------------------------------- | ----------------------------------------------- |
| Settings | Display Name                     | Navigation links                                |
| Settings | API ID                           | navigationLinks                                 |
| Settings | `Allow multiple values` checkbox | Select this checkbox                            |
| Settings | Select component                 | Use the dropdown to select the "Link" component |

![Simple navigation - Link component](/images/docs/recipes/navigation/navigation-simple-link.png)

We'll click `Add` to save. In this case, we've allowed multiple values so that we can add as many links as we want to our navigation.

<Alert theme="info" title="Pro Tip">
We've created a simple navigation model that contains components, as well as other schema elements, and that allows you to add internal content entries and external links.

You could potentially use this model to create different navigation elements for your project.
</Alert>

![Simple navigation](/images/docs/recipes/navigation/navigation-simple.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our navigation recipes.

Check out the next document section for that!

## Useful links

- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This recipe shows you how to create a simple navigation model using Hygraph. If you want to try out something more complex, we have a [Styled navigation](/docs/recipes/navigation/navigation-styled/) and a [Sectioned navigation](/docs/recipes/navigation/navigation-sectioned/) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Styled navigation

Source: https://hygraph.com/docs/recipes/navigation/navigation-styled

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a styled navigation using enumerations and components.

Our styled navigation will be a content model containing an ID, a component field that allows multiple values, and a dropdown to select styling options. This way, to create a navigation using this configuration, you can create a content entry with its own ID, and as many navigation items as you need.

This is the type of navigation model you want if your project has different styling options available.

Here, by adding styling option dropdown menus for size and theme, you'll give Editors the possibility to style the navigation using the options you provide.

Dropdowns are great for this, because while they have options, it will only be within a limited selection that ensures the whole project has a cohesive look & feel.

It is also a great option for large projects that have continuous updates, since it includes a toggle button that lets you indicate if a menu item is new!

![Styled navigation](/images/docs/recipes/navigation/navigation-styled.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the cookbook project.](/docs/recipes/navigation/navigation-styled#clone-project) This is the way to go if you're curious about how the Navigation elements are made but don't want to follow the step-by-step creation process. This project contains the entire **Navigation Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 3:` **Use an existing project of yours.** If you have a project already and want to add this Navigation to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with enumerations, references, components and basic component fields. Let's look into these concepts:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

- **References:** 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.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/navigation/navigation-styled/#step-by-step-guide) Use this guide to create a styled navigation that you can use in your Hygraph projects.
- [Path 2:](/docs/recipes/navigation/navigation-styled/#clone-project) Clone the project that contains the entire **Navigation cookbook** to compare the different navigation configurations without having to clone multiple projects.

## Clone project

We have prepared a project that contains the entire **Navigation cookbook**:

<Button
  href="https://app.hygraph.com/clone/4c6eeda2afc048b39cda460d24bb1d7f?name=Hygraph%20Recipes%20-%20Navigation"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create navigations, so you can compare the different navigation configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for **"Styled Navigation"**.

## Step-by-step guide

Before we can build our **Styled Navigation**, we need to create other schema elements that we can later add to it.

To make this guide easier to follow, we've divided it in steps for you.

### 1. Create the models

We'll start by creating three sample models - Product, Store, and Blog - that we will use as referenceable models later to create our navigation items.

<Alert theme="info" title="Pro Tip">
In a real situation, you would use actual content models that you planned and built for your project, but for the sake of this example, we will simply create three empty content models so we can later on reference them.
</Alert>

We'll click `+ Add` next to **Models** and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Product |
| API ID        | Product  |
| API ID Plural | Products |

We'll click `Add Model` to save.

![Create the models](/images/docs/recipes/navigation/navigation-styled-models.png)

Normally, we'd add fields to these models, but for the sake of this example, we'll simply leave them empty.

Repeat the process to create a second model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Blog |
| API ID        | Blog  |
| API ID Plural | Blogs |

We'll click `Add Model` to save.

And one final time for our third model:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Store |
| API ID        | Store  |
| API ID Plural | Stores |

We'll click `Add Model` to save.

Finally, we will create one more model for our styled navigation, using the following information:

| Field         | Input             |
| ------------- | ----------------- |
| Display Name  | Styled Navigation |
| API ID        | StyledNavigation  |
| API ID Plural | StyledNavigations |

We'll click `Add Model` to save. This model won't stay empty, but before we can start adding fields to it, we need to build an enumeration and a component.

### 2. Create a navigation item component

We want our navigation to contain a **navigation item** component that will allow you to add multiple links to your navigation.

We'll click `+ Add` next to **Components** and use this information:

| Field         | Input           |
| ------------- | --------------- |
| Display Name  | Navigation item |
| API ID        | NavigationItem  |
| API ID Plural | NavigationItems |

![Navigation item component](/images/docs/recipes/navigation/navigation-styled-component-navitem.png)

We'll click `Add component` to save. 

We can now start adding instances to this component. We'll start by adding a `Single line text` field by clicking on it on the **Add fields** right sidebar.

We'll use the following information:

| Tab         | Field                          | Input                |
| ----------- | ------------------------------ | -------------------- |
| Settings    | Display Name                   | Link label           |
| Settings    | API ID                         | linkLabel            |
| Settings    | `Use as title field` checkbox  | Select this checkbox |
| Validations | `Make field required` checkbox | Select this checkbox |

![Navigation item - Label](/images/docs/recipes/navigation/navigation-styled-component-label.png)

We'll click `Add` to save. This field will let us add a label to our links.

Next, we want our navigation to indicate if an item is new. To do this, we'll add a `boolean` field using the following information:

| Tab      | Field        | Input           |
| -------- | ------------ | --------------- |
| Settings | Display Name | New item toggle |
| Settings | API ID       | newItemToggle   |

![Navigation item - Toggle](/images/docs/recipes/navigation/navigation-styled-component-toggle.png)

We'll click `Add` to save. 

We want our navigation to offer the possibility to add both internal and external links. We'll add a reference for the internal links, and a slug field for the external ones. In this case, we won't be making them required fields, because users will either use one or the other.

We'll start with the reference field. We'll find the `Reference` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab                 | Field                | Input                                                              |
| ------------------- | -------------------- | ------------------------------------------------------------------ |
| Define              | Reference type       | Select `Allow multiple models to be referenced (Union Type)`       |
| Define              | Models to reference  | Use the dropdown menu to select `Product`, `Blog` and `Store` |
| Define              | Reference direction  | Select `One-way reference`                                         |
| Define              | Relation cardinality | Select  `One to One`                                               |
| Configure reference | Display Name         | Page                                                               |
| Configure reference | API ID               | page                                                               |

![Navigation item - Reference](/images/docs/recipes/navigation/navigation-styled-component-reference.png)

We'll click `Add` to save. We've configured the reference in such a way that when we find this field in a content entry, it will allow us to select an entry from the models that we configured.

Finally, we'll add a `slug` field for our external URLs, using the following information:

| Tab         | Field                               | Input                                                                                                                                                                        |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | External Link                                                                                                                                                                |
| Settings    | API ID                              | externalLink                                                                                                                                                                 |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                 |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `URL` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Navigation item - External URL](/images/docs/recipes/navigation/navigation-styled-component-url.png)

We'll click `Add` to save.

### 3. Create a theme enumeration

We want our navigation to allow choosing a theme. To do this, we'll create an enumeration that we can later add to our **Navigation** model.

We'll click `+ Add` next to **Enumerations** and use the following information:

| Field        | Input            |
| ------------ | ---------------- |
| Display Name | Navigation theme |
| API ID       | NavigationTheme  |

![Themes enumeration](/images/docs/recipes/navigation/navigation-styled-enum-theme.png)

We'll click `Add` to save.

Next, we need to add enumeration values. These are the options we will get when using this later on as a dropdown menu. For this example, we'll use two theme options - light and dark.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Light        | light  |
| Dark         | dark   |

![Themes enumeration values](/images/docs/recipes/navigation/navigation-styled-enum-themevalues.png)

We'll click `Add enumeration` to save.

### 4. Add fields to the Navigation model

We'll go back into our **Styled Navigation** model now, to add fields to it. The reason we're creating this navigation as a model, is so that we can then create an entry per navigation that we want to build using this configuration.

First, we will add a `slug` field that will be our navigation ID. We'll click on the `Slug` field in the **Add fields** right sidebar and use the following information:

| Tab         | Field                               | Input                                                                                                                                                                         |
| ----------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display Name                        | Navigation ID                                                                                                                                                                 |
| Settings    | API ID                              | navigationId                                                                                                                                                                  |
| Settings    | `Lowercase` checkbox                | Leave this checkbox selected                                                                                                                                                  |
| Settings    | `Use as title field` checkbox       | Select this checkbox                                                                                                                                                          |
| Validations | `Set field as unique` checkbox      | Leave this checkbox selected                                                                                                                                                  |
| Validations | `Match a specific pattern` checkbox | Leave this checkbox selected, and use the dropdown to select the `Slug` pattern. Write "Input value does not match the expected format." in the `Custom error message` field. |

![Navigation model - ID](/images/docs/recipes/navigation/navigation-styled-model-id.png)

We'll click `Add` to save.

Now it is time to add the navigation item component that we created earlier. We'll click on the `Basic component` field in the **Add fields** right sidebar and use the following information:

| Tab      | Field                            | Input                                                      |
| -------- | -------------------------------- | ---------------------------------------------------------- |
| Settings | Display Name                     | Navigation items                                           |
| Settings | API ID                           | navigationItems                                            |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                       |
| Settings | Select component                 | Use the dropdown to select the "Navigation item" component |

![Navigation model - Navigation item](/images/docs/recipes/navigation/navigation-styled-model-navitem.png)

We'll click `Add` to save. In this case, we've allowed multiple values, because that way we can add as many links as we want to our navigation.

Finally, we'll add the **theme** enumeration that we created earlier. We'll find the `Enumeration` field on the **Add fields** sidebar, and add it using this information:

| Tab      | Field        | Input                                            |
| -------- | ------------ | ------------------------------------------------ |
| Settings | Display Name | Theme                                            |
| Settings | API ID       | theme                                            |
| Settings | Enumeration  | Select "Navigation theme" from the dropdown menu |

![Navigation model - Theme](/images/docs/recipes/navigation/navigation-styled-model-theme.png)

We'll click `Add` to save.

<Alert theme="info" title="Pro Tip">
We've created a styled navigation model that contains enumerations, components, as well as other schema elements, and that allows you to add internal content entries and external links.

You could potentially use this model to create different navigation elements for your project.
</Alert>

Our styled navigation model should look like this:

![Styled navigation](/images/docs/recipes/navigation/navigation-styled.png)

This guide helped you create the schema element yourself. Alternatively, you can clone a project containing all our navigation recipes.

Check out the next document section for that!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

- [Simple navigation:](/docs/recipes/navigation/navigation-simple/) Learn how to build a simple navigation model containing menu items with basic information.
- [Sectioned navigation:](/docs/recipes/navigation/navigation-sectioned/) Learn how to build a sectioned navigation that lets you group your menu items into clusters.
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Navigation overview

Source: https://hygraph.com/docs/recipes/navigation/section-index

## Overview

In this section, you will find recipes that you can use to create **navigation elements** using different field configurations.

| Recipe                                                                | Description                                                 |
| --------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Simple navigation](/docs/recipes/navigation/navigation-simple/)           | Learn how to create a simple navigation                     |
| [Styled navigation](/docs/recipes/navigation/navigation-styled/)           | Learn how to create a navigation with style dropdowns       |
| [Sectioned navigation](/docs/recipes/navigation/navigation-sectioned/)     | Learn how to create navigation with internal sections       |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Navigation Cookbook

We have prepared a project that contains the entire **Navigation cookbook**:

<Button
  href="https://app.hygraph.com/clone/4c6eeda2afc048b39cda460d24bb1d7f?name=Hygraph%20Recipes%20-%20Navigation"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create navigation elements, so you can compare the different navigation configurations without having to clone multiple projects.


---
# Landing page

Source: https://hygraph.com/docs/recipes/page-sections/landing-page

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create a landing page model that contains three modular components - header, sections, and footer - each of which contains different section configurations to select from. 

You will create a dynamic content model that will allow you to preserve the same page structure while also creating a variety of content pieces.

This recipe uses other recipes & cookbooks to build the different sections, and finally adds them all as part of a modular component field that will simplify your content entries.

![Landing page model](/images/docs/recipes/page-sections/landing-page-model.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/page-sections/landing-page#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create the page sections, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/page-sections/landing-page#clone-the-complete-cookbook) This is the way to go if you're curious about how the page sections are made but don't want to follow the step-by-step creation process. This project contains the entire **Page Sections Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this page section to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Modular component field**: a modular component field can have two or more components attached to it. 

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/page-sections/landing-page#step-by-step-guide) Use this guide to create a landing page model with a predefined sections structure.
- [Path 2:](/docs/recipes/page-sections/landing-page#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the page sections right away, or you can clone the project that contains the entire **Page sections cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to add to your page sections, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/2723e18145f4445eaaed3675fc5da1ba?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/page-sections/landing-page#2-create-the-model).

### Clone the complete cookbook

We have prepared a project that contains the entire **Page sections cookbook**:

<Button
  href="https://app.hygraph.com/clone/7bd49d6761784a6f9d8c796e4eefc56d?name=Hygraph%20Recipes%20-%20Page%20Sections"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create page sections, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Landing page"** model.

## Step-by-step guide

In this guide, we will create a landing page model with nested component fields for to create the sections that will form the structure of the page. Before we can build our landing page model, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create sections:** This part of the guide brings it recipes from this and other cookbooks, so we can have a number of page sections to add to our section component.
2. **Create the landing page model:** We will build a model that will contain all the other sections we brought into the project as part of nested modular component fields.

### 1. Create sections

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the creation of models & other schema elements, and only want to follow the parts of the tutorial related to the multi-purpose page section component, you can clone a project that we've prepared for you. It contains all the schema elements that you will use in [step 2](/docs/recipes/page-sections/landing-page#2-create-the-model)! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/page-sections/landing-page#2-create-the-model) to continue the tutorial.

</Alert>

Since this recipe combines existing sections into one single landing page model, we'll bring in sections from different cookbooks.

If you want to follow the step-by-step to create each section, you can follow the links to do that, and then come back to continue:

- <Link href="/docs/recipes/headers-and-footers/header-notification" target="_blank"><b>Header with notification</b></Link>
- <Link href="/docs/recipes/headers-and-footers/header-links" target="_blank"><b>Header with links</b></Link>
- <Link href="/docs/recipes/headers-and-footers/footer-links" target="_blank"><b>Footer with links</b></Link>
- <Link href="/docs/recipes/headers-and-footers/footer-sections" target="_blank"><b>Footer with sections</b></Link>
- <Link href="/docs/recipes/image-gallery/image-gallery-styled" target="_blank"><b>Styled image gallery</b></Link>

Great! Now that we have all our sections, we can move on to creating the model!

### 2. Create the model

<VideoEmbed videoId="NFh4ziudzTI" />

Now that we have all the schema elements that, both directly and indirectly, will be a part of our final landing page model, we'll go ahead and create it!

![Landing page model](/images/docs/recipes/page-sections/landing-page-model.png)

We'll click `+ Add` next to **Models** and add it using this information:

| Field         | Input        |
| ------------- | ------------ |
| Display Name  | Landing page |
| API ID        | LandingPage  |
| API ID Plural | LandingPages |

We'll click `Add model` to save, and then we'll start adding fields to it.

We will start by adding a `Single line text` field from the right sidebar. Since all the components we'll add to this model already have their own title fields, this field is only meant to be used as title field for the model only, and will not be used as part of the content.

Let's add it by clicking `Add` on the `Single line text` field card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                                                                           |
| -------- | ----------------------------- | ------------------------------------------------------------------------------- |
| Settings | Display Name                  | Page name                                                                       |
| Settings | API ID                        | pageName                                                                        |
| Settings | Description                   | This field is used as title field only and won't be used as part of the content |
| Settings | `Use as title field` checkbox | Select this checkbox                                                            |

We'll click `Add` to save.

Whether you followed the step-by-step tutorial for each individual recipe, or cloned the basic project, by now your project has a number of components for different page sections. We will now add them as part of three `Modular component` fields, so when we use each section in a content entry, we will be able to select which component to include.

Let's start with the header. We'll find the `Modular component` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab      | Field                     | Input                                                                                   |
| -------- | ------------------------- | --------------------------------------------------------------------------------------- |
| Settings | Display Name              | Header                                                                                  |
| Settings | API ID                    | header                                                                                  |
| Settings | Description               | Select a header                                                                         |
| Settings | Select allowed components | Use the dropdown to select the "Header with notification" and "Header links" components |

We'll click `Add` to save.

Next, we'll repeat the process for the sections that will be the body of our page, using the following information:

| Tab      | Field                     | Input                                                               |
| -------- | ------------------------- | ------------------------------------------------------------------- |
| Settings | Display Name              | Sections                                                            |
| Settings | API ID                    | sections                                                            |
| Settings | Description               | Use this to add sections to your page                               |
| Settings | Select allowed components | Use the dropdown to select the "FAQ" and "Image gallery" components |

We'll click `Add` to save.

<Alert theme="info" title="Pro Tip">

In a project with other section components already built in, you could easily add them to the component field above. In this case we are only using FAQ and Image gallery, because they are available in the basic project.

</Alert>

Finally, we'll repeat the process once more for the footer, using the following information:

| Tab      | Field                     | Input                                                                           |
| -------- | ------------------------- | ------------------------------------------------------------------------------- |
| Settings | Display Name              | Footer                                                                          |
| Settings | API ID                    | footer                                                                          |
| Settings | Description               | Pick the footer you want to use                                                 |
| Settings | Select allowed components | Use the dropdown to select the "Sectioned footer" and "Footer links" components |

We'll click `Add` to save.

This is how you create a landing page model containing modular component fields that allow you to add different section types. 

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a landing page model using Hygraph. If you want to try out more section configurations, we have other [page section types](/docs/recipes/page-sections/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Multi-purpose section

Source: https://hygraph.com/docs/recipes/page-sections/multi-purpose-section

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a multi-purpose page section component that you can use to add a number of different section types to your content.

This recipe uses other recipes & cookbooks to build the different sections, and finally adds them all as part of a modular component field that will simplify your content entries.

![Multi-purpose section component](/images/docs/recipes/page-sections/multi-purpose-section-component.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/page-sections/multi-purpose-section#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create the page sections, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/page-sections/multi-purpose-section#clone-the-complete-cookbook) This is the way to go if you're curious about how the page sections are made but don't want to follow the step-by-step creation process. This project contains the entire **Page Sections Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this page section to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **Enumerations:** an enumeration is a predefined set of values that represents a list of possible options. You can use them to group values within a type.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Modular component field**: a modular component field can have two or more components attached to it. 

- **Nested components:** Nested components allow you to create component fields within a component, as if you had a parent component containing one or more child components.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/page-sections/multi-purpose-section#step-by-step-guide) Use this guide to create a multi-purpose section component that you can use in your project.
- [Path 2:](/docs/recipes/page-sections/multi-purpose-section#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the page sections right away, or you can clone the project that contains the entire **Page sections cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to add to your page sections, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/2723e18145f4445eaaed3675fc5da1ba?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/page-sections/multi-purpose-section#2-create-the-section-component).

### Clone the complete cookbook

We have prepared a project that contains the entire **Page sections cookbook**:

<Button
  href="https://app.hygraph.com/clone/7bd49d6761784a6f9d8c796e4eefc56d?name=Hygraph%20Recipes%20-%20Page%20Sections"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create page sections, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Section"** component.

## Step-by-step guide

In this guide, we will create a multi-purpose section component with a nested component field for links. Before we can build this, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create sections:** This part of the guide brings it recipes from this and other cookbooks, so we can have a number of page sections to add to our section component.
2. **Create the section component:** We will build a section component that will contain all the other sections we brought into the project as part of a nested modular component field.

### 1. Create sections

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the creation of models & other schema elements, and only want to follow the parts of the tutorial related to the multi-purpose page section component, you can clone a project that we've prepared for you. It contains all the schema elements that you will use in [step 2](/docs/recipes/page-sections/multi-purpose-section#2-create-the-section-component)! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/page-sections/multi-purpose-section#2-create-the-section-component) to continue the tutorial.

</Alert>

Since this recipe combines existing sections into one single landing page model, we'll bring in sections from different cookbooks.

If you want to follow the step-by-step to create each section, you can follow the links to do that, and then come back to continue:

- <Link href="/docs/recipes/headers-and-footers/header-notification" target="_blank"><b>Header with notification</b></Link>
- <Link href="/docs/recipes/headers-and-footers/header-links" target="_blank"><b>Header with links</b></Link>
- <Link href="/docs/recipes/headers-and-footers/footer-links" target="_blank"><b>Footer with links</b></Link>
- <Link href="/docs/recipes/headers-and-footers/footer-sections" target="_blank"><b>Footer with sections</b></Link>
- <Link href="/docs/recipes/image-gallery/image-gallery-styled" target="_blank"><b>Styled image gallery</b></Link>

Great! Now that we have all our sections, we can move on to creating the model!

### 2. Create the section component

<VideoEmbed videoId="dc-nyQq1sUA" />

Now that we have all the schema elements that, both directly and indirectly, will be a part of our final multi-purpose section component, we'll go ahead and create it!

![Multi-purpose section component](/images/docs/recipes/page-sections/multi-purpose-section-component.png)

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input    |
| ------------- | -------- |
| Display Name  | Section  |
| API ID        | Section  |
| API ID Plural | Sections |

We'll click `Add component` to save, and then we'll start adding instances to it.

We will start by adding a `Single line text` field from the right sidebar. Since all the sections we'll add to this component already have their own title fields, this field is only meant to be used as title field for the component only, and will not be used as part of the content.

Let's add it by clicking `Add` on the `Single line text field` card on the right sidebar.

We'll use the following information:

| Tab      | Field                         | Input                                                                           |
| -------- | ----------------------------- | ------------------------------------------------------------------------------- |
| Settings | Display Name                  | Section name                                                                    |
| Settings | API ID                        | sectionName                                                                     |
| Settings | Description                   | This field is used as title field only and won't be used as part of the content |
| Settings | `Use as title field` checkbox | Select this checkbox                                                            |

We'll click `Add` to save.

Whether you followed the step-by-step tutorial for each individual recipe, or cloned the basic project, by now your project has a number of components for different page sections. We will now add them as part of a `Modular component` field, so when we use it in a content entry, we will be able to select which component to include.

We'll find the `Modular component` field on the **Add fields** right sidebar, click on it, and use the following information:

| Tab      | Field                            | Input                                                                                                                                                |
| -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings | Display Name                     | Blocks                                                                                                                                               |
| Settings | API ID                           | blocks                                                                                                                                               |
| Settings | `Allow multiple values` checkbox | Select this checkbox                                                                                                                                 |
| Settings | Select allowed components        | Use the dropdown to select the "Header with notification", "Header links", "Footer links", "Sectioned footer", "FAQ", and "Image gallery" components |

We'll click `Add` to save.

Finally, since we already have a theme enumeration created in our project, we will add it as an enumeration field that will let us select a section theme when we use this component in a content entry:

We'll find the `Enumeration` field on the **Add fields** sidebar, and click `Add` on the field card.

We'll use the following information:

| Tab      | Field        | Input                                 |
| -------- | ------------ | ------------------------------------- |
| Settings | Display Name | Section theme                         |
| Settings | API ID       | sectionTheme                          |
| Settings | Enumeration  | Select "Theme" from the dropdown menu |

We'll click `Add` to save.

This is how you create a multi-purpose page section component containing a number of different section types. Creating the section as a component, allows you to reuse the structure in different models in your project as if it were a template!

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a multi-purpose section using Hygraph. If you want to try out more section configurations, we have other [page section types](/docs/recipes/page-sections/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Related content block

Source: https://hygraph.com/docs/recipes/page-sections/related-content-block

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to build a related content block component containing a title, a body, an image, and a reference.

It will allow you to add related content blocks to your content entries.

![Related content block component](/images/docs/recipes/page-sections/related-content-block.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><b>you can sign up here.</b></Link>
- `REQUIRED:` You need to have a Hygraph project.
  - `OPTION 1:` <Link href="/docs/getting-started/fundamentals/quickstart#create-a-project" target="_blank"><b>Create a project.</b></Link> This is the way to go if you want to follow the entire tutorial for learning purposes.
  - `OPTION 2:` [Clone the basic project.](/docs/recipes/page-sections/related-content-block#clone-the-basic-project) If you're already familiar with Hygraph and only want to follow the parts of the tutorial where you create the page sections, you can start here.
  - `OPTION 3:` [Clone the entire cookbook.](/docs/recipes/page-sections/related-content-block#clone-the-complete-cookbook) This is the way to go if you're curious about how the page sections are made but don't want to follow the step-by-step creation process. This project contains the entire **Page Sections Cookbook** so you can compare them, or look into what instances they contain.
  - `OPTION 4:` **Use an existing project of yours.** If you have a project already and want to add this page section to it, this is the way to go. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><b>plan limits</b></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our <Link href="/docs/getting-started/onboarding-overview" target="_blank"><b>Getting Started Tutorial!</b></Link>

</Alert>

## Core concepts

In this guide, you'll work with a number of schema elements. Let's look into them:

- **References:** 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.

- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once, and then fill them with different content every time you use it in a content entry.

- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one, or allow multiple component instances to be added in the content entry.

## What you can do

This guide offers two paths:

- [Path 1:](/docs/recipes/page-sections/related-content-block#step-by-step-guide) Use this guide to create a related content block component that you can use in your project.
- [Path 2:](/docs/recipes/page-sections/related-content-block#clone-project) Clone one of the projects we created for you. You can clone a project that only contains the basic models so you can work on the page sections right away, or you can clone the project that contains the entire **Page sections cookbook** to compare the different section configurations without having to clone multiple projects.

## Clone project

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to add to your page sections, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/2723e18145f4445eaaed3675fc5da1ba?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of this tutorial, and [start from this step](/docs/recipes/page-sections/related-content-block#2-create-the-related-content-block-component).

### Clone the complete cookbook

We have prepared a project that contains the entire **Page sections cookbook**:

<Button
  href="https://app.hygraph.com/clone/7bd49d6761784a6f9d8c796e4eefc56d?name=Hygraph%20Recipes%20-%20Page%20Sections"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create page sections, so you can compare the different banner configurations without having to clone multiple projects.

To find this particular recipe in the cookbook project, navigate to the schema and look for the **"Related content block"** component.

## Step-by-step guide

In this guide, we will create a related content block component. Before we can build this, we need to create other schema elements that will be a part of it.

We will divide this process in steps to make it more manageable:

1. **Create the referenced models:** We will create 3 sample models - Author, Book, and Shop - to use in our internal links.
2. **Create the related content block component:** We will create a related content block component that you can later add as component field to your models.

### 1. Create the basic models

<Alert theme="info" title="Would you like to skip this step?">

If you're already familiar with the model building process, you can clone a project that we've prepared for you. It contains the basic models that you need for this recipe! 

<Link href="https://app.hygraph.com/clone/8f1b296a5da346d5bcd00d5c2c5330dd?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20models%20only)" target="_blank">Click here to clone the project</Link> and [skip over to the next section](/docs/recipes/page-sections/related-content-block#2-create-the-related-content-block-component) to continue the tutorial.

</Alert>

For this example, we'll go with the idea of an online bookshop that has real world subsidiaries, so we'll create 3 models:

- Author
- Book
- Shop

#### Author model

![Author model](/images/docs/recipes/page-sections/page-sections-author-model.png)

Let's start with the **Author** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input   |
| ------------- | ------- |
| Display Name  | Author  |
| API ID        | Author  |
| API ID Plural | Authors |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic author information, we'll add the author name, bio, and image.

Let's start with the author name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Author name                  |
| Settings | API ID                        | authorName                   |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our author's bio. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Author bio |
| Settings | API ID       | authorBio  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our author's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Author image |
| Settings | API ID       | authorImage  |

We'll click `Add` to save.

Now that we're done with our **Author** model, let's move on to the **Book** model.

#### Book model

![Book model](/images/docs/recipes/page-sections/page-sections-book-model.png)

Our second model will be the **Book** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Book  |
| API ID        | Book  |
| API ID Plural | Books |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic book information, we'll add the book name, description, cover image, and a relation to the author.

Let's start with the book name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Book name                    |
| Settings | API ID                        | bookName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will our book description. We'll select the `Rich text` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display Name | Book description |
| Settings | API ID       | bookDescription  |

We'll click `Add` to save.

Now let's add an `Asset picker` field, which will be our book cover image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Book cover |
| Settings | API ID       | bookCover  |

We'll click `Add` to save.

Finally, we want books and authors to be connected. A great way to do this is using a two-way reference in our **Book** model, that will create a relation with the **Author** model. This type of relation will also create a reverse field that we will later be able to see in our **Author** model, connecting back to our **Book** model.

We'll find the `Reference` field on the **Add fields** right sidebar,  and click `Add` on the field card to add it.

We'll use the following information:

| Tab                     | Field                        | Input                                                                         |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| Define                  | Reference type               | Select `Allow only one model to be referenced`                                |
| Define                  | Models to reference          | Use the dropdown menu to select `Author`                                      |
| Define                  | Reference direction          | Select `Two-way reference`                                                    |
| Define                  | `Allow multiple...` checkbox | Select  `Allow multiple Book per Author` and `Allow multiple Author per Book` |
| Configure reference     | Display Name                 | Author                                                                        |
| Configure reference     | API ID                       | Author                                                                        |
| Configure reverse field | Display Name                 | Book                                                                          |
| Configure reverse field | API ID                       | book                                                                          |

We'll click `Add` to save.

Now that we're done with our **Book** model, let's move on to the **Shop** model.

#### Shop model

![Shop model](/images/docs/recipes/page-sections/page-sections-shop-model.png)

Our final model is the **Shop** model. In the **Schema builder**, we'll click `+Add` next to **Models**, and use the following information:

| Field         | Input |
| ------------- | ----- |
| Display Name  | Shop  |
| API ID        | Shop  |
| API ID Plural | Shops |

We'll click `Add model` to save.

Our model has been created but it's empty. To create a simple model that will contain basic shop information, we'll add the shop name, address, picture and location.

Let's start with the shop name, as a `Single line text` field. We'll find it on the **Add fields** right sidebar, and click `Add` on the field card to add it.

We'll use the following information:

| Tab      | Field                         | Input                        |
| -------- | ----------------------------- | ---------------------------- |
| Settings | Display Name                  | Shop name                    |
| Settings | API ID                        | shopName                     |
| Settings | `Use as title field` checkbox | Leave this checkbox selected |

We'll click `Add` to save.

Next, we'll add another `Single line text` field for the shop address. 

We'll use the following information:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop address |
| Settings | API ID       | shopAddress  |

We'll click `Add` to save.

Finally, we'll add an `Asset picker` field, which will be our shop's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input        |
| -------- | ------------ | ------------ |
| Settings | Display Name | Shop picture |
| Settings | API ID       | shopPicture  |

We'll click `Add` to save.

Finally, we'll add a location field so Editors can show the shop location on a map. We'll select the `Location` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input    |
| -------- | ------------ | -------- |
| Settings | Display Name | Location |
| Settings | API ID       | location |

We'll click `Add` to save.

Now that we're done with our three models, let's create our links component!

### 2. Create the related content block component

<VideoEmbed videoId="kdPd66tADPY" />

Now that we have all the models that we need to relate to our related content block component, we'll go ahead and create it!

![Related content block component](/images/docs/recipes/page-sections/related-content-block.png)

We'll click `+ Add` next to **Components** and add it using this information:

| Field         | Input                 |
| ------------- | --------------------- |
| Display Name  | Related content block |
| API ID        | RelatedContentBlock   |
| API ID Plural | RelatedContentBlocks  |

We'll click `Add component` to save, and then we'll start adding instances to it.

We want our block to have a title, a body, an image and we also want the possibility to relate existing content entries from the other models to it.

We'll start with the title. Let's add a `Single line text` field using the following information:

| Tab      | Field                         | Input                |
| -------- | ----------------------------- | -------------------- |
| Settings | Display Name                  | Block title          |
| Settings | API ID                        | blockTitle           |
| Settings | `Use as title field` checkbox | Select this checkbox |

We'll click `Add` to save.

Next, we'll add a `Rich text` field, which will be our block body:

| Tab      | Field        | Input      |
| -------- | ------------ | ---------- |
| Settings | Display Name | Block body |
| Settings | API ID       | blockBody  |

We'll click `Add` to save.

Next, we'll add an `Asset picker` field, which will be our block's image. We'll select the `Asset picker` field from the right sidebar and use the following information to create it:

| Tab      | Field        | Input       |
| -------- | ------------ | ----------- |
| Settings | Display Name | Block image |
| Settings | API ID       | blockImage  |

We'll click `Add` to save.

Finally, we will add a `Reference` field from the right sidebar, so we can use it to relate content entries from other models. 

We'll use the following information:

| Tab                 | Field               | Input                                                        |
| ------------------- | ------------------- | ------------------------------------------------------------ |
| Define              | Reference type      | Select `Allow multiple models to be referenced (Union Type)` |
| Define              | Models to reference | Use the dropdown menu to select `Author`, `Book`, and `Shop` |
| Define              | Reference direction | Select `One-way reference`                                   |
| Configure reference | Display Name        | Related content                                              |
| Configure reference | API ID              | relatedContent                                               |

We'll click `Add` to save.

This is how you create a simple content block component containing some basic information - title, body and image - and the possibility to reference content entries from other models in your schema.

## Useful links

- [Enumerations](/docs/developer-guides/schema/using-enumerations)
- [Components documentation](/docs/developer-guides/schema/components)
- [References documentation](/docs/developer-guides/schema/references)

<Alert theme="info" title="Would you like to know more?">
We have more resources for you!

This is one way of creating a related content block component using Hygraph.  If you want to try out more section configurations, we have other [page section types](/docs/recipes/page-sections/section-index) for you to look into!
</Alert>

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Page sections overview

Source: https://hygraph.com/docs/recipes/page-sections/section-index

## Overview

In this section, you will find recipes that you can use to create **Page sections** using different field configurations.

| Recipe                                                                      | Description                                                                                                                   |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [Landing page](/docs/recipes/page-sections/landing-page)                    | Learn how to create a dynamic landing page model that will allow you to create different landing page configurations          |
| [Multi-purpose section](/docs/recipes/page-sections/multi-purpose-section)  | Learn how to create a multi-purpose section component that you can add as a block selector to different models in your schema |
| [Related content block](/docs/recipes/page-sections/related-content-block/) | Learn how to create a component that will allow you to add related content blocks to your content entries                     |

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

## Page sections cookbook

### Clone the basic project

We have prepared a project that contains all the base schema elements you need to add to your page sections, in case you don't want to build them from scratch:

<Button
  href="https://app.hygraph.com/clone/2723e18145f4445eaaed3675fc5da1ba?name=Hygraph%20Recipes%20-%20Page%20Sections%20(Basic%20project)"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

If you decide to clone this project, you can skip the base schema elements creation part of these tutorials, and start from the final step in each recipe.

### Clone the complete cookbook

We have prepared a project that contains the entire **Page sections cookbook**:

<Button
  href="https://app.hygraph.com/clone/7bd49d6761784a6f9d8c796e4eefc56d?name=Hygraph%20Recipes%20-%20Page%20Sections"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cookbook contains all the recipes we have so far to create page sections, so you can compare the different banner configurations without having to clone multiple projects.


---
# Set up personalization with Hygraph's Variants and frontend logic

Source: https://hygraph.com/docs/recipes/personalization/personalization-example-variants-frontend-logic

This guide is ideal for anyone who’s new to personalization or looking to experiment with simple, practical ways to tailor content. Whether you’re exploring how to deliver more relevant interactions or just want to test out basic strategies, you'll learn how to use Hygraph’s Variants together with frontend logic to create targeted content for different audience groups.

To get started, you can use the data you already have, such as purchase history, location, or browsing behavior, to create simple rules for personalization. This information could come from targeted email segments, dynamic website banners, or purchase and browsing history. Implementing personalization without investing in any additional tools shows its benefits and helps you see what resonates with your audience.

## Use cases

Personalized content helps improve engagement, relevance, and conversion rates. You can personalize content for your users in several ways.

<Alert theme="info" title="Pro Tip">

Combining methods such as, campaign segmentation, direct input, and profile-based personalization, creates the most comprehensive strategy for delivering meaningful, user-focused experiences.
</Alert>

### Campaign segmentation

Show specific content to users depending on the campaign or referral link that brought the user to your website.

**Setup**

1. Set up tracking parameters in your campaign URLs.
2. Define logic that matches each campaign to the right content.
3. Display targeted content or offers when users land on your site.

**Example**

If you’re running two coffee bean campaigns, one on Instagram aimed at home baristas and another on Etsy targeting coffee shop owners, you can determine which content to show based on their needs.

### User input

Collect your users' preferences when they arrive at your website.

**Setup**

1. Prompt visitors to select the role or category they identify with when they arrive on your website.
2. Store their answer in a persistent cookie or session variable.
3. Use this stored preference to serve relevant content across pages and future visits.

**Example**

A visitor who selects “Coffee shop owner” will continue to see wholesale offers and bulk order options, while a “Home barista” might see guides and starter kits.

### User profile

If users have accounts or a history of past purchases, you can utilize that data to recommend and display personalized content tailored to their preferences and behavior.

**Setup**

1. Collect information, such as preferences and demographics, from your users' accounts.
2. Leverage purchase history or browsing behavior to recommend relevant products.
3. Update content dynamically as the user’s activity evolves.

**Example**

A returning customer who previously purchased dark roast beans might be shown new arrivals in similar flavors or bundle deals with grinders.

## How it works

You can deliver personalized content to your users using Hygraph and your frontend logic.

1. **Identify the user’s role.** Use your own frontend logic to determine a user’s role. This step does not require a Customer Data Platform (CDP).
2. **Map the role to a segment and variant in Hygraph.** Each role corresponds to a segment in Hygraph, and each segment is linked to a specific content variant. This setup allows you to deliver the right content automatically, without relying on a separate personalization engine.

## Setup in Hygraph

1. [Enable Variant support for fields in your schema](/docs/developer-guides/schema/variants#enable-variant-support-for-fields). You can enable variants for as many fields from the base content entry, per your requirement. It is not necessary to mark all schema fields as variant-enabled fields.
    - For the `Article` schema, we have enabled variant support for the `Title`, `Summary`, `Content`, and `Picture` fields.

      <VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmfpgvpj8622k07ur8spuvrfm" caption="Enable variant support on Article schema" />

2. [Add Segments](/docs/beta-guides/variants-guide#add-a-segment). In this example, we have two segments:
    - Segment `Coffee Shop Owners` with slug `shops`
    - Segment `Home Baristas` with slug `home`

      <VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmfpgtf6p5yyg07urnj5qo24o" caption="Add Segments for personalization" />


3. [Add Variants of the base entry and link it to Segments](/docs/beta-guides/variants-guide#add-a-variant-and-link-it-to-a-segment).
    - The base entry `Understanding Coffee Bean Origins` includes two variants, one for the `Coffee Shop Owners` segment and the other for the `Home Baristas` segment.

      <VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmfpgul2n60k607urdds4copi" caption="Add Variants and link to Segments" />

## Display personalized content

### Overview

The following is a high-level overview of the steps that you need to run through to display personalized content to your users:

1. Retrieve the segment from the search parameters, a cookie, or the user’s profile via the customers database.
2. Extract the article `id` parameter from the route or request object.
3. Fetch the article by ID and its variants that are linked to the segment.
4. If an article is found, overlay the variant fields on top of the base article. If no variant is found, return the article as is. If no article is found, throw an error.

    ```ts
      const segment = await getSegment(searchParams);
      const { id } = await params;
      let article = await getArticleById(id, segment);
      if (!article) {
        return {
          title: "Article Not Found",
          description: "The requested article could not be found.",
        };
      }
      article = applyVariant(article);
    ```

### Step-by-step process

1. Retrieve the segment from the search parameters or cookies.

    ```ts
      export async function getSegment(
      searchParams: Promise<{ segment?: string }>,
    ): Promise<string | undefined> {
      const { segment } = await searchParams;
      const cookieStore = await cookies();
      const cookieSegment = cookieStore.get("segment");
      return segment || cookieSegment?.value;
    }
    ```

2. Query the variant content, and pass the segment `slug` as a filter.

    ```ts
    // Query article including variants
    export type ArticleType = {
      id: string;
      title: string;
      summary: string;
      variants: {
        title: string;
        summary: string;
        content: {
          raw: string;
          html: string;
      };
      picture: {
        thumbnailUrl: string;
        url: string;
      };
      }[];
      content: {
        raw: string;
        html: string;
      };
      picture: {
        thumbnailUrl: string;
        url: string;
      };
      createdAt: string;
    };

    // Get a single article by ID
    export async function getArticleById(
      id: string,
      segment?: string,
    ): Promise<ArticleType | null> {
      const query =
        `
        query ArticleByIdQuery($id: ID!, $segment: String) {
          article(where: {id: $id}) {
            id

            title
            summary
            content {
              raw
              html
            }
            picture {
              thumbnailUrl: url(
                transformation: {image: {resize: {width: 800, height: 600}}
                document: {output: {format: webp}}}
              )
              url: url(
                transformation: {image: {resize: {height: 1440}}
                document: {output: {format: webp}}}
              )
            }
            createdAt

            variants(where:{
                segments_some:{
                  slug: $segment
                }
              }) {
              title
              summary
              content {
                raw
                html
              }
              picture {
                thumbnailUrl: url(
                  transformation: {
                    image: { resize: { width: 800, height: 600 } }
                    document: { output: { format: webp } }
                  }
                )
                url: url(
                  transformation: {
                    image: { resize: { height: 1440 } }
                    document: { output: { format: webp } }
                  }
                )
              }
            }
          }
        }
      `;

      try {
        const data = await fetchFromCMS(query, { id, segment });
        return data.article;
      } catch (error) {
        console.error(`Error fetching article with ID ${id}:`, error);
        return null;
      }
    }

3. Now, merge the article values with variant values. The following code snippet builds a single `data` object by combining:
    - All the base article fields, and
    - All the fields of its first variant, with variant fields overriding article fields if there’s a conflict.

    ```
    // Merges a variant onto the base entry
    export function mergeVariant<T extends Record<string, any>>(
      data: T,
      variant?: Partial<T>,
    ): T {
      if (!variant) {
        return data;
      }
      return {
        ...data,
        ...variant,
      };
    }
    ```

4. Now, pick the first merged variant, and display it to your user.
    ```
    // Pick the first merged variant
    export function applyVariant<
      T extends Record<string, any> & { variants: Array<Partial<T>> },
    >(data: T): T {
      return mergeVariant(data, data.variants[0]);
    }
    ```


---
# Achieve Personalization with Hygraph's Variants

Source: https://hygraph.com/docs/recipes/personalization/personalization-variants

Personalization delivers tailored experiences to your users by matching content to the right audience segment at the right time. Nowadays, users are more likely to engage with your brand if you personalize their journey. Providing this level of personalization influences purchasing decisions, conversions, customer loyalty, and ultimately drives revenue and growth for your brand.

With Hygraph, you can implement personalization consistently across all channels.

## Key terms

- Variants - These define WHAT you deliver. You can create multiple variants of a main content entry.
- Segments - These define WHO you deliver the content to. Define segments based on user attributes, behavior, or context, via a Customer Data Platform (CDP).
- Personalization rules - These define HOW and WHEN you deliver the content. Set up your own logic or use a personalization engine to decide which content should be delivered to which segment in real time.

## Solution components

- Hygraph (Headless CMS) – Centralizes content variants and segment creation, as well as tagging for omnichannel delivery.
- Customer Data Platform (CDP) – Maintains unified, real-time user profiles and generates user lists that map to the segments created in Hygraph.
- Personalization engine – Applies business logic to deliver relevant experiences across different touchpoints.

## How it works

![Personalization - How it works](/images/docs/beta-guides/personalization-solution-how-it-works.png)

1. To deliver a personalized experience to a user, some internal logic determines the applicable segment for a user by evaluating attributes and context data of the user. In this example, the user matches `Segment 2`.
2. The personalization engine looks up content to be delivered, and, if available, finds the content variant. In this example, `Variant 2` was assigned to `Segment 2` by the editor.
3. The user sees the variant as the personalized experience. If no matching variant exists, the default content is delivered to the user.

## Example: Personalization with Hygraph

Let's make the following assumptions:

- The content team created content entries, such as the main content entry and its variants in Hygraph.
- The Customer Data Platform (CDP) contains real-time behavioral and contextual user data.
- The personalization engine decides the content, products, offers, or UI that a user sees based on their data and context.

The following example illustrates a headless personalization workflow for a returning customer to your website.

1. A customer returns to your website. The HTTP request from their browser to your server includes a cookie from their last visit. This cookie contains a unique, anonymous ID.
2. Your web server receives the incoming request, and recognizes a unique ID in the request. Instead of fetching the default, static page, it launches server-to-server API calls to other personalization components.
3. The server sends the customer's anonymous ID to the Customer Data Platform (CDP). The CDP immediately returns her unified customer profile to the web server in its API response, which includes the following data points:
    - Segments - High-value customers, Running enthusiasts
    - Browsing history - Recently viewed Running shoes model X
    - Purchase history - Running socks
    - Location - Cold weather region
4. The web server sends this customer profile to the personalization engine. The engine's AI model processes the inputs in real-time, and makes the following decisions:
    - Show a banner featuring waterproof running shoes Z
    - Recommendations for gear frequently bought with running shoes
    - Highlight offer - Free Shipping
  This personalization engine returns a structured list of specific content components required to build this experience for your customer, in its API response to the web server.
5. Now, the web server requests the following from Hygraph:
    - Variant `HeroBanner` with information for waterproof running shoes Z linked to the `Running enthusiasts` Segment
    - Variant `RecommendationSection` with information for trail gear linked to `Running enthusiasts` Segment
    - Variant `OfferText` with information for VIP shipping linked to the `High-value customers` Segment

    In its API response, Hygraph returns raw JSON objects for content entries, including fields such as image URLs, product IDs, and text, which are passed to the web server.
6. The server combines the frontend presentation template and the personalized content from Hygraph, and displays it in your customer's browser.

If the customer is using your mobile app instead of a web browser, they would see the same personalized content there. Likewise, if they were shopping in-store on a kiosk, the same experience would be displayed. <Link href="https://hygraph.com/use-cases/content-personalization" target="_blank">By using a headless CMS like Hygraph</Link>, you can ensure that content remains consistent and up-to-date across all channels, delivering a seamless digital experience regardless of how customers choose to interact with your products.

<Alert theme="info" title="Pro Tip">

- You can start with Hygraph's Variants and Segments, and create basic customer matching logic. You can later introduce the personalization engine and Customer Data Platform (CDP) for automation and omnichannel coverage.
- Integrate analytics and A/B testing to evaluate how your personalization impacts conversions and revenue growth.

</Alert>

## Next steps

Learn how to set up personalization step by step, beginning with a simple approach that does not require a CDP or a personalization engine. You can use existing customer data and rules to deliver tailored experiences, without any additional, dedicated tools.

<Button
  href="/docs/recipes/personalization/personalization-example-variants-frontend-logic"
  size="md"
  variant="solid"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Example - Set up personalization with Hygraph's Variants and frontend logic</Button>



---
# Product page with Akeneo

Source: https://hygraph.com/docs/recipes/product-page/product-page-akeneo

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

![Product Page model](/images/docs/recipes/product-page/akeneo-productpagemodel.png)

This guide shows how to create a Product model in Hygraph that fetches product information from an external PIM (Akeneo) via app integrations.

Companies often store their product information in a PIM, which helps them keep it consistent across different platforms. Using Akeneo, one of our integrated apps, you can send CMS and product information to your frontend with a single API call. 

Using this information directly from the PIM ensures you won't have to keep track of PIM information updates being replicated in the CMS, reducing the chance of error and discrepancies.

This recipe is a great option if you are already using Akeneo as your external PIM. You should have some Akeneo knowledge and some product data already set up in your Akeneo account to use this recipe.

This mock image shows what a frontend using this setup could look like:

![Product Page mock image](/images/docs/recipes/product-page/mock-image-akeneo.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. [Look into the following section to learn more about your options.](/docs/recipes/product-page/product-page-akeneo#what-you-can-do)
- `REQUIRED:` You must have an **Akeneo** account. If you don't have one yet, you can start a free trial <Link href="https://www.akeneo.com/start-free-trial/" target="_blank"><strong>here</strong></Link> or request a demo <Link href="https://www.akeneo.com/demo/" target="_blank"><strong>here</strong></Link>.
- `REQUIRED:` You must have your <Link href="https://www.akeneo.com/what-is-a-pim/" target="_blank"><strong>Akeneo PIM</strong></Link> ready. Your PIM is the URL of your Akeneo account. You can copy it from the browser directly; it should look similar to this `https://<YOUR-PROJECT-NAME>.cloud.akeneo.com/`.
- `REQUIRED:` You must create connection settings for your Hygraph project. To do this, go to **Connect > Connection settings** in your Akeneo dashboard, and click `Create`. You'll need to provide a `Label` and a `Code` to identify the app, then use the `Flow type` dropdown to select `Data source`.
    - This takes you to your Akeneo credentials: the `Client ID`, `Secret`, `Username`, and `Password`. Akeneo will show you your `Secret` and `Password` credentials only once, so make sure you save them somewhere.

### What you can do

Use this guide to create a **Product Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/product-page/section-index#product-pages-cookbook)

This is the way to go if you're curious about how we built the Product Pages but don't want to follow the step-by-step creation process. This project contains the entire **Product Page Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Product Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Apps:** Apps are a core aspect of Hygraph's extensibility. They extend the capabilities of your Hygraph project by bringing in functionality from tools and services you're accustomed to using within your workflows.

## Step-by-step guide

<VideoEmbed videoId="o0CGYcrywIE" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Install the Akeneo app

![Install the Akeneo app](/images/docs/recipes/product-page/akeneo-install-app.png)

Click <Link href="https://hygraph.com/marketplace/apps/hygraph-akeneo-app" target="_blank">here</Link> to access our Marketplace page for the Akeneo integration. This app allows you to fetch data from your Akeneo PIM into Hygraph.

To install the app, click `Install Akeneo for Hygraph` and [follow the instructions in our integration guide](/docs/integrations/connect-akeneo#install-the-akeneo-app).

Later on, you will add this app as a field to your Product model. Let's move on to the next step, where you create the model itself.

### 2. Create the model

![Product Page model](/images/docs/recipes/product-page/akeneo-productpagemodel.png)

To create the product model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                                                                         |
| ------------- | ----------------------------------------------------------------------------- |
| Display name  | Product Page Akeneo                                                           |
| API ID        | ProductPageAkeneo                                                             |
| API ID Plural | ProductPagesAkeneo                                                            |
| Description   | This product page model uses an app to fetch information from your Akeneo PIM |

Click `Add Model` to save.

Now that the model has been created, you can start adding fields to it. As the product information lives outside of the CMS, this model does not need to have a large number of fields. Besides the app fields that we're going to add, we will also add a name, title, slug and asset picker, so editors can add alternative information to go along with some of the information living in the PIM.

You can make your frontend take the alternative data when offered; that way editors can use the product information in the PIM not only for product listings but also for promotional content such as product special offers.

We will also add a reference field that will allow editors to link related products in the content form.

Let's start with the name. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Product name                 |
| Settings    | API ID                | productName                  |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |

Click `Add` to save.

We want the name to be a required field as it only exists so that editors can easily identify products in the content table when adding related products to a content entry.

The other fields (title, slug and asset picker) will not be required, because this is additional information that editors may or may not add for the frontend to pick up.

Let's continue with the product title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab      | Field        | Input         |
| -------- | ------------ | ------------- |
| Settings | Display name | Product title |
| Settings | API ID       | productTitle  |

Click `Add` to save.

Next, we'll add the slug. Add a `Slug` field from the right sidebar, and use the following information:

| Tab         | Field                      | Input                                                                                                                                                                                       |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display name               | Product slug                                                                                                                                                                                |
| Settings    | API ID                     | productSlug                                                                                                                                                                                 |
| Settings    | `Lowercase`                | Leave this checkbox selected                                                                                                                                                                |
| Validations | `Set field as unique`      | Select this checkbox                                                                                                                                                                        |
| Validations | `Match a specific pattern` | Select this checkbox, and then select `Slug` from the dropdown. You don't need to modify the pattern. Under `Custom error message`, write “Input value does not match the expected format.” |

Click `Add` to save.

Next, you want editors to be able to include at least one image in the content form. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field                   | Input                   |
| -------- | ----------------------- | ----------------------- |
| Settings | Display name            | Product image           |
| Settings | API ID                  | productImage            |
| Settings | `Allow multiple assets` | Select this checkbox    |
| Settings | Description             | You can add images here |

Click `Add` to save.

After installing the Akeneo app, an app field became available to add to our models. Find the Akeneo Field Picker on the right sidebar and click `Add` on the field card.

Use the following information:

| Tab      | Field        | Input                         |
| -------- | ------------ | ----------------------------- |
| Settings | Display name | Product information           |
| Settings | API ID       | productInformation            |
| Settings | Description  | You can select a product here |

Click `Add` to save.

We're not allowing multiple values here, because we want to select only one product from the PIM per product entry in the CMS. If your workflow requires that you add more than one product from the PIM per product entry, you could alternatively select the `Allow multiple values` checkbox in the field configuration screen.

Finally we'll add a `Reference` field so that editors have the possibility to link related product entries. Use the following information:

| Tab       | Field                                                        | Input                                              |
| --------- | ------------------------------------------------------------ | -------------------------------------------------- |
| Define    | `Allow only one model to be referenced`                      | Select this radio button.                          |
| Define    | Model to reference                                           | use the dropdown to select `Product Page Akeneo`   |
| Define    | Reference direction                                          | Use the radio button to select `One-way reference` |
| Define    | Relation cardinality                                         | One to many                                        |
| Define    | `Allow multiple Product Page Akeneo per Product Page Akeneo` | Select this checkbox                               |
| Configure | Display name                                                 | Related products                                   |
| Configure | API ID                                                       | relatedProducts                                    |
| Configure | Description                                                  | You can add related products here                  |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">
This reference configuration will allow editors to add links to multiple content entries, but only from the same model. 


If you want editors to select entries from more than one model, you should configure the reference to `Allow multiple models to be referenced`. 

If you want your editors to add more than one entry from each model, you will need to select all the `Allow multiple` checkboxes as well.
</Alert>

This is how you build a Product model that uses an app to fetch data from the Akeneo PIM.

When editors create product content entries, they will be able to use the Akeneo product picker to select the products that you have stored in the external PIM. You can send all this information, along with the data already in the CMS, to your front end with a single API call.

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9syjatg07w5ui6b7mhy" caption="Content form" />

Editors will be able to open the Akeneo asset selection screen directly from the content form.

---
# Product page for eCommerce

Source: https://hygraph.com/docs/recipes/product-page/product-page-ecommerce

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

![Product Page model](/images/docs/recipes/product-page/ecommerce-productpagemodel.png)

This guide shows how to create a Product model for eCommerce with Product information stored in the CMS.

Whether you decide to use an external PIM as the source of truth for your product information and copy/paste the information in Hygraph or create and store all of your product information in the CMS only, this recipe shows an efficient way to combine schema elements to create a product page that contains basic product information and uses components for product variants and related product listings.

This mock image shows what a frontend using this setup could look like:

![Product Page mock image](/images/docs/recipes/product-page/mock-image-ecommerce.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. [Look into the following section to learn more about your options.](/docs/recipes/product-page/product-page-ecommerce#what-you-can-do)

### What you can do

Use this guide to create a **Product Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/product-page/section-index#product-pages-cookbook)

This is the way to go if you're curious about how we built the Product Pages but don't want to follow the step-by-step creation process. This project contains the entire **Product Page Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Product Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **Modular component field**: a modular component field can have two or more components attached.
- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one or allow multiple component instances to be added to the content entry.
- **Nested components:** functionality that allows you to create components within a component as if you had a parent component containing one or more child components.
- **Enumerations:** an enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="w8uYkYj54hc" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the enumerations

Our Product Page model will contain component fields containing enumeration fields for color and size. Since it's best to start building from the bottom up, we'll start with the enumerations.

![Enumerations list](/images/docs/recipes/product-page/enumerations-list.png)

#### Clothing size enumeration

![Clothing size enumeration](/images/docs/recipes/product-page/ecommerce-enumeration-clothingsize.png)

Navigate to the **Schema builder** of your Hygraph project, and click `+Add` next to **Enumerations** on the left sidebar. We'll use the following information to create the first one:

| Field        | Input         |
| ------------ | ------------- |
| Display name | Clothing size |
| API ID       | ClothingSize  |

The next step is to add enumeration values, which are the options you will get when using this later as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| L            | l      |
| M            | m      |
| S            | s      |
| XL           | xl     |
| XS           | xs     |

Finally, click `Add enumeration` to save.

#### Shoes size enumeration

![Shoes size enumeration](/images/docs/recipes/product-page/ecommerce-enumeration-shoesize.png)

You'll repeat the process to create an enumeration for shoes size.

You'll use the following information to create the enumeration:

| Field        | Input      |
| ------------ | ---------- |
| Display name | Shoes size |
| API ID       | ShoesSize  |

You'll add the following values to that enumeration:

| Display name | API ID |
| ------------ | ------ |
| Size 35      | size35 |
| Size 36      | size36 |
| Size 37      | size37 |
| Size 38      | size38 |
| Size 39      | size39 |
| Size 40      | size40 |
| Size 41      | size41 |

Click `Add enumeration` to save.

#### Item color enumeration

![Item color enumeration](/images/docs/recipes/product-page/ecommerce-enumeration-itemcolor.png)

Finally, we'll create one last enumeration to hold the list of item colors. Use the following information to create the enumeration:

| Field        | Input      |
| ------------ | ---------- |
| Display name | Item color |
| API ID       | ItemColor  |

You'll add the following values to that enumeration:

| Display name | API ID |
| ------------ | ------ |
| Black        | black  |
| Blue         | blue   |
| Green        | green  |
| Red          | red    |
| White        | white  |
| Pink         | pink   |

Click `Add enumeration` to save.

Now that you have created the 3 enumerations that you need to add to your components, it's time to create those components.

### 2. Create the components

In this section you'll create components for clothes and shoes, that you will later nest into a product variant component. This will allow you to simply add a product variant to the product model and let editors decide what product to add information about in the content form by selecting a product type.

![Components list](/images/docs/recipes/product-page/components-list.png)

#### Clothing component

![Clothing component](/images/docs/recipes/product-page/ecommerce-component-clothing.png)

In the **Schema builder**, click `+Add` next to **Components** and use the following information:

| Field         | Input              |
| ------------- | ------------------ |
| Display name  | Clothing component |
| API ID        | ClothingComponent  |
| API ID Plural | ClothingComponents |

Click `Add component` to save.

Now that you've created the component itself, it's time to add fields to it. You'll add two of the enumerations that you created in the previous step of this guide.

Find the `Enumeration` field on the right sidebar, click `Add`, and use the following information to create the enumeration:

| Tab         | Field                 | Input                                            |
| ----------- | --------------------- | ------------------------------------------------ |
| Settings    | Display name          | Size                                             |
| Settings    | API ID                | size                                             |
| Settings    | Enumeration           | Use the dropdown menu to select `Clothing size`. |
| Settings    | Description           | Select a size for the clothing item              |
| Validations | `Make field required` | Select this checkbox                             |

Click `Add` to save.

You'll now repeat the process to add the next enumeration field, using the following information:

| Tab         | Field                 | Input                                         |
| ----------- | --------------------- | --------------------------------------------- |
| Settings    | Display name          | Color                                         |
| Settings    | API ID                | color                                         |
| Settings    | Enumeration           | Use the dropdown menu to select `Item color`. |
| Settings    | Description           | Select a color for the clothing item          |
| Validations | `Make field required` | Select this checkbox                          |

Click `Add` to save.

#### Shoes component

![Shoes component](/images/docs/recipes/product-page/ecommerce-component-shoes.png)

The next component you should create is the shoes component. Click `+Add` next to **Components** and use the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | Shoes component |
| API ID        | ShoesComponent  |
| API ID Plural | ShoesComponents |

Click `Add component` to save.

Just like with the previous component, you'll add enumerations for size & color to this one.

Find the `Enumeration` field on the right sidebar, click `Add`, and use the following information to create the enumeration:

| Tab         | Field                 | Input                                         |
| ----------- | --------------------- | --------------------------------------------- |
| Settings    | Display name          | Size                                          |
| Settings    | API ID                | size                                          |
| Settings    | Enumeration           | Use the dropdown menu to select `Shoes size`. |
| Settings    | Description           | Select a shoe size                            |
| Validations | `Make field required` | Select this checkbox                          |

Click `Add` to save.

You'll now repeat the process to add the next enumeration field, using the following information:

| Tab         | Field                 | Input                                         |
| ----------- | --------------------- | --------------------------------------------- |
| Settings    | Display name          | Color                                         |
| Settings    | API ID                | color                                         |
| Settings    | Enumeration           | Use the dropdown menu to select `Item color`. |
| Settings    | Description           | Select an item color                          |
| Validations | `Make field required` | Select this checkbox                          |

Click `Add` to save.

#### Product variant component

![Product variant component](/images/docs/recipes/product-page/ecommerce-component-productvariant.png)

By now, you've created two components, each containing enumerations that will allow editors to select a color & size for the items. For the **Product variant component** we'll use a modular component field that will offer the option to select the clothing or shoes components in the content form. This makes the content form more dynamic and avoids having fields in it that the editors won't use.

<Alert theme="info" title="Pro Tip">
Shorter content forms are easier for editors to work with. Make sure to always think about your editors and their workflow when building a schema.
</Alert>

First, you'll create the component using the following information:

| Field         | Input           |
| ------------- | --------------- |
| Display name  | Product variant |
| API ID        | ProductVariant  |
| API ID Plural | ProductVariants |

Click `Add component` to save.

This component will only contain a `Modular component` field. Find it on the right sidebar and click `Add`.

Use the following information:

| Tab      | Field                       | Input                                                                       |
| -------- | --------------------------- | --------------------------------------------------------------------------- |
| Settings | Display name                | Product type                                                                |
| Settings | API ID                      | productType                                                                 |
| Settings | Description                 | Select the product type to reveal fields                                    |
| Settings | `Select allowed components` | Use the dropdown menu to select `Clothing component` and `Shoes component`. |

<Alert theme="info" title="Pro Tip">
In this case, we don't allow multiple values because the idea is to use this component to add only one product to a product listing.
</Alert>

### 3. Create the model

![Product Page model](/images/docs/recipes/product-page/ecommerce-productpagemodel.png)

Now it's time to create the **Product Page** model. Keep in mind that this model contemplates information being stored in the CMS, so we'll include all the information needed to create a product listing. This does not necessarily mean this information exists *only* in the CMS, as it could be copy-pasted from an external source that a company uses to store their product information.

You'll create the model first. In the **Schema builder**, click `+Add` next to `Models`, and use the following information:

| Field         | Input                  |
| ------------- | ---------------------- |
| Display name  | Product Page eCommerce |
| API ID        | ProductPageECommerce   |
| API ID Plural | ProductPagesECommerce  |

Click `Add Model` to save.

Product listings in an eCommerce normally show the name, a description, at least one image, and the price. In addition to this, the model will have a product slug, in case the frontend needs this to build a custom URL, the product variant component that you built earlier, and the ability to link related products using a reference field.

You'll start with the product name. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                              |
| ----------- | --------------------- | ---------------------------------- |
| Settings    | Display name          | Product name                       |
| Settings    | API ID                | productName                        |
| Settings    | Description           | Write the name of the product here |
| Settings    | `Use as title field`  | Leave this checkbox selected       |
| Validations | `Make field required` | Select this checkbox               |
| Validations | `Set field as unique` | Select this checkbox               |

Click `Add` to save.

This configuration prevents editors from creating products without a name, as well as giving the same name to more than one product.

Next, for the product slug, add a `Slug` field from the right sidebar, and use the following information:

| Tab         | Field                      | Input                                                                                                                                                                                       |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display name               | Product slug                                                                                                                                                                                |
| Settings    | API ID                     | productSlug                                                                                                                                                                                 |
| Settings    | `Lowercase`                | Leave this checkbox selected                                                                                                                                                                |
| Validations | `Set field as unique`      | Leave this checkbox selected                                                                                                                                                                        |
| Validations | `Match a specific pattern` | Leave this checkbox selected, and then select `Slug` from the dropdown. You don't need to modify the pattern. Under `Custom error message`, write “Input value does not match the expected format.” |

Click `Add` to save.

Next, you want editors to be able to include at least one image in the content form. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field                   | Input                                       |
| -------- | ----------------------- | ------------------------------------------- |
| Settings | Display name            | Product image                               |
| Settings | API ID                  | productImage                                |
| Settings | Description             | Add one or more images for the product here |
| Settings | `Allow multiple assets` | Select this checkbox                        |

Click `Add` to save.

Next, you want the product to have a description by including a rich text field, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field              | Input                                                                                   |
| -------- | ------------------ | --------------------------------------------------------------------------------------- |
| Settings | Display name       | Product description                                                                     |
| Settings | API ID             | productDescription                                                                      |
| Settings | Description        | Add a product description here                                                          |
| Settings | `Enable embedding` | Select this checkbox and use the dropdown to select the `Product Page eCommerce` model. |

Click `Add` to save.

It's time to add the **Product variant** component that you built earlier. Add a `Basic component` field from the right sidebar, using the following information:

| Tab      | Field              | Input                                         |
| -------- | ------------------ | --------------------------------------------- |
| Settings | Display name       | Product variant                               |
| Settings | API ID             | productVariant                                |
| Settings | Description        | Select a product type                         |
| Settings | Select a component | Use the dropdown to select `Product variant`. |

Click `Add` to save.

We now need to include a field for the price of the product. Add a `Float` field from the right sidebar, using the following information:

| Tab      | Field        | Input                      |
| -------- | ------------ | -------------------------- |
| Settings | Display name | Product price              |
| Settings | API ID       | productPrice               |
| Settings | Description  | Add the product price here |

Click `Add` to save.

This product listing needs one more thing: The ability to add related products. 

You can do this by creating a reference field that will allow editors to add content entries from this very model.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                                              | Input                                               |
| --------- | ------------------------------------------------------------------ | --------------------------------------------------- |
| Define    | `Allow only one model to be referenced`                            | Select this radio button.                           |
| Define    | Model to reference                                                 | use the dropdown to select `Product Page eCommerce` |
| Define    | Reference direction                                                | Use the radio button to select `One-way reference`  |
| Define    | Relation cardinality                                               | One to many                                         |
| Define    | `Allow multiple Product Page eCommerce per Product Page eCommerce` | Select this checkbox                                |
| Configure | Display name                                                       | Related products                                    |
| Configure | API ID                                                             | relatedProducts                                     |
| Configure | Description                                                        | Add related products here                           |

Click `Add` to save.

This reference configuration will allow editors to add links to multiple content entries, but only from the `Product Page eCommerce` model.

Your model is ready! 

<Alert theme="info" title="Pro Tip">
There is no one-size-fits-all for all possible product model configurations, so when you create your own product page model, remember to give some serious thought to what you'll be selling. 

Study what information a potential buyer would need to buy the product, as well as what information a developer would need to create a frontend for you product listings.
</Alert>

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9wyhu6e07vxzm3yqthd" caption="Content form" />

Editors will be able to create new product entries, using a dynamic content form that allows them to load the fields for the required product type only.

## Useful links

- [Components documentation:](/docs/developer-guides/schema/components) Learn more about components, available component field types, and how to use them.
- [Enumerations:](/docs/developer-guides/schema/using-enumerations) Learn more about enumerations and how to configure them.
- [References:](/docs/developer-guides/schema/references) Learn more about the different reference field types and how to configure them.

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Product page with a Remote Source

Source: https://hygraph.com/docs/recipes/product-page/product-page-remote-source

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

![Product Page model](/images/docs/recipes/product-page/remote-sources-productpagemodel.png)

This guide shows how to create a Product model in Hygraph that fetches product information from an external PIM via Remote Sources.

Companies often store their product information in a PIM, which helps them keep it consistent across different platforms. Using Hygraph's content Federation feature, Remote Sources, you can send CMS and product information to your frontend with a single API call.

Using this information directly from the PIM ensures you won't have to keep track of PIM information updates being replicated in the CMS, reducing the chance of error and discrepancies.

This mock image shows what a frontend using this setup could look like:

![Product Page mock image](/images/docs/recipes/product-page/mock-image-remotesources.png)

<Alert theme="warning" title="Remote Sources usage">
Our Remote Sources feature is not available in Hobby plans (free). To follow this step-by-step tutorial you need to either have a paid plan, or use our 30-day trial.
</Alert>

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here</strong></Link>.
- `REQUIRED:` You need to have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project). If you have a <Link href="https://hygraph.com/pricing" target="_blank">Hobby plan</Link>, please use the 30-day trial to enable usage of Remote Sources in your project.

### What you can do

Use this guide to create a **Product Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema. Remember that Hobby plan projects cannot use Remote Sources.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/product-page/section-index#product-pages-cookbook)

This is the way to go if you're curious about how we built the Product Pages but don't want to follow the step-by-step creation process. This project contains the entire **Product Page Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Product Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Remote source:** A Remote Source is a custom resolver entry point for your schema that allows data to be sourced from an external third-party web service and accept field values from other Hygraph fields as arguments.
- **Remote Field:** A field inside a regular Hygraph model that connects specific remote data to an entry of that model. Remote Fields are always related to a single remote source and custom type. RESTful remote fields are configured with a path to a specific endpoint in the remote source, such as user details from Github, or price & availability from Shopify.
- **Top Level Remote Field:** A field inside the `Query` system model in Hygraph. These fields fetch remote data outside the context of a regular model, which is then sent to your frontend alongside your Hygraph data. This [**Content Federation**](/docs/core-concepts/content-federation) utility eliminates the need to make separate API requests for data inside & outside of Hygraph.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="AfbY-wuuQ9Q" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Configure the Remote Source

![Configure the Remote Source](/images/docs/recipes/product-page/remote-sources-configuresource.png)

First, you need to configure a remote source to ensure that the project can use remote data fetched from your external PIM.

This guide will use the <Link href="https://www.federatethis.com/routes/skncre/" target="_blank">Federate this SKNCRE product routes</Link> to simulate an external PIM so you can follow the complete step-by-step process.

In your Hygraph project, navigate to the **Schema builder** and click `+Add` next to **Remote Sources**. Use the following information to configure the remote source:

| Field                     | Input                                                                         |
| ------------------------- | ----------------------------------------------------------------------------- |
| Select remote source type | Use the radio buttons to select `Custom source`.                              |
| Display name              | Federate This SKNCRE                                                          |
| Prefix                    | FederateThisSkncre                                                            |
| Description               | Check out <Link href="https://federatethis.com/" target="_blank">https://federatethis.com</Link> for more info |
| Type                      | Use the radio buttons to select `GraphQL`                                     |
| Base URL                  | https://federatethis.com/api/graphql/skncre                                   |
| Introspection method      | Use the radio buttons to select `POST`                                        |

Click `Add remote source` to save.

This remote source will use the data stored in **Federate This**, using the **Base URL** you provided to send queries to. Since we created a GraphQL type remote source, there was no need to provide custom type definitions to define the structure of input arguments passed to your remote field later on.

The remote source itself is not enough to fetch information into a project. This project will use remote fields, top-level remote fields, and a data picker for remote fields app to create a product page that uses information from your external PIM without the need to duplicate it, while remaining easy to use for editors working with the UI.

We'll start by installing the picker app.

### 2. Install the picker app

![Install the picker app](/images/docs/recipes/product-page/remote-sources-installapp.png)

Click <Link href="https://hygraph.com/marketplace/apps/remote-source-data-picker" target="_blank">here</Link> to install the Remote Source Data Picker app. This app gives your editors the ability to pick data from a Remote Source using a dropdown menu.

To install the app:

1. <Link href="https://hygraph.com/marketplace/apps/remote-source-data-picker" target="_blank">Go to the app page in our marketplace</Link>, and click `Install the app`.
2. Select a project and an environment.
3. Authorize permissions.

You will reach this screen:

![Install the picker app](/images/docs/recipes/product-page/remote-source-data-picker-install.png)

Click `Install App` to finalize the process.

Later on, you will add this app as a field to your Product model. Let's move on to the next step, where you create a Top-level Remote Field.

### 3. Create the Top-level Remote Field

![Top-level Remote Field](/images/docs/recipes/product-page/remote-sources-toplevelrf.png)

Top-level Remote Fields are added to the Query system model, and can fetch information into a project outside the context of a specific model. The picker app that we installed in the previous step needs both a Remote Field inside the Product model and a Top-level Remote Field to work.

To create a Top-level Remote Field, go to the **Schema builder** and access the **Query** system model. Since we created a GraphQL remote source, find the GraphQL field on the right sidebar and click `Add` on the field card. Use the following information:

| Tab      | Field         | Input                                                   |
| -------- | ------------- | ------------------------------------------------------- |
| Settings | Display name  | Top level product                                       |
| Settings | API ID        | topLevelProduct                                         |
| Settings | Remote Source | Use the dropdown menu to select `Federate This SKNCRE`. |
| Settings | Method        | Use the dropdown menu to select `POST`.                 |
| Settings | Query         | Select the `products [Product!]` checkbox.              |

Click `Add` to save.

Our product picker app will use this field to fetch product information from the external PIM.

Now that we have everything we need to build the model, let's move on to the final step.

### 4. Create the model

![Product Page model](/images/docs/recipes/product-page/remote-sources-productpagemodel.png)

To create the product model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                                                                                 |
| ------------- | ------------------------------------------------------------------------------------- |
| Display name  | Product Page remote source                                                            |
| API ID        | ProductPageRemoteSource                                                               |
| API ID Plural | ProductPageRemoteSources                                                              |
| Description   | This product page model uses remote sources to fetch information from an external PIM |

Click `Add Model` to save.

Now that the model has been created, you can start adding fields to it. As the product information lives outside of the CMS, this model does not need to have a large number of fields. Besides the remote fields and the picker, we will add a name, title, slug and asset picker, so editors can add alternative information. You can make your frontend take the alternative data when offered; that way editors can use the product information in the PIM not only for product listings but also for promotional content such as product special offers.

We will also add a reference field that will allow editors to link related products in the content form.

Let's start with the name. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Product name                 |
| Settings    | API ID                | productName                  |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |

Click `Add` to save.

We want the name to be a required field because this field exists so that editors can identify products in the content table when relating content later on.

The other fields (title, slug and asset picker) will not be required, because this is additional information that editors may or may not add for the frontend to pick up.

Let's continue with the product title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab      | Field        | Input         |
| -------- | ------------ | ------------- |
| Settings | Display name | Product title |
| Settings | API ID       | productTitle  |

Click `Add` to save.

Next, we'll add the slug. Add a `Slug` field from the right sidebar, and use the following information:

| Tab         | Field                      | Input                                                                                                                                                                                       |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settings    | Display name               | Slug                                                                                                                                                                                        |
| Settings    | API ID                     | slug                                                                                                                                                                                        |
| Settings    | `Lowercase`                | Leave this checkbox selected                                                                                                                                                                |
| Validations | `Set field as unique`      | Select this checkbox                                                                                                                                                                        |
| Validations | `Match a specific pattern` | Select this checkbox, and then select `Slug` from the dropdown. You don't need to modify the pattern. Under `Custom error message`, write “Input value does not match the expected format.” |

Click `Add` to save.

Next, you want editors to be able to include at least one image in the content form. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field                   | Input                |
| -------- | ----------------------- | -------------------- |
| Settings | Display name            | Promotional image    |
| Settings | API ID                  | promotionalImage     |
| Settings | `Allow multiple assets` | Select this checkbox |

Click `Add` to save.

After installing the data picker app, 2 app fields became available to add to our models: One for GraphQL and one for REST. Since we configured a GraphQL Remote Source, we'll find the GraphQL Data Picker on the right sidebar and we'll click `Add` on the field card.

Use the following information:

| Tab      | Field          | Input                         |
| -------- | -------------- | ----------------------------- |
| Settings | Display name   | Product picker RS             |
| Settings | API ID         | productPickerRs               |
| Settings | Description    | You can select a product here |
| Custom   | ID Field ID    | id                            |
| Custom   | API ID         | topLevelProduct               |
| Custom   | Title Field ID | name                          |

Click `Add` to save.

Regarding the custom fields:

- **ID Field ID:** This is the key the app uses to find what data to pick as the `ID` that gets used in the remote source field. We haven't added this remote field yet, we'll do it in the next step.
- **API ID:** This is the API ID of the Top-level Remote Field that you configured earlier.
- **Title Field ID:** This is the key from the data that shows the app what to display in the dropdown menu in the content form for editors to select.

The next thing we need to add to this model, is a Remote Field. Together with the Top-level Remote Field that you configured in the previous step, they will allow you to configure a field for the picker app that you installed earlier.

Find the `GraphQL` field on the right sidebar, and click `Add`. Use the following information:

| Tab      | Field            | Input                                                                                                                            |
| -------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Settings | Display name     | Remote product data                                                                                                              |
| Settings | API ID           | remoteProductData                                                                                                                |
| Settings | Remote Source    | Use the dropdown menu to select `Federate This SKNCRE`.                                                                          |
| Settings | Method           | Use the dropdown menu to select `POST`.                                                                                          |
| Settings | Query            | Select the `product` checkbox and the `id` argument `checkbox`under it, then write `{{doc.productPickerRs}}` in the input field. |
| Advanced | Field visibility | Use the dropdown menu to select `API only`.                                                                                      |

Click `Add` to save.

When configuring `Settings > Query` we selected  `id` to match the `ID Field ID` from the data picker, and defined it as `{{doc.productPickerRs}}` so it uses the data picker app field.

As this field is only necessary to configure the remote data picker correctly, we selected the visibility to be `API only`, so editors cannot see it in the content form.

Finally we'll add a `Reference` field so that editors have the possibility to link related products. Use the following information:

| Tab       | Field                                                                      | Input                                                   |
| --------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
| Define    | `Allow only one model to be referenced`                                    | Select this radio button.                               |
| Define    | Model to reference                                                         | use the dropdown to select `Product Page remote source` |
| Define    | Reference direction                                                        | Use the radio button to select `One-way reference`      |
| Define    | Relation cardinality                                                       | One to many                                             |
| Define    | `Allow multiple Product Page remote source per Product Page remote source` | Select this checkbox                                    |
| Configure | Display name                                                               | Related products                                        |
| Configure | API ID                                                                     | relatedProducts                                         |
| Configure | Description                                                                | You can add related products here                       |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">
This reference configuration will allow editors to add links to multiple content entries, but only from the same model.


If you want editors to select entries from more than one model, you should configure the reference to `Allow multiple models to be referenced`.

If you want your editors to add more than one entry from each model, you will need to select all the `Allow multiple` checkboxes as well.
</Alert>

This is how you build a Product model that uses Remote Sources to fetch data from an external PIM. The way we built it is user-friendly for editors, who will be able to select product data using a dropdown menu in the content form.

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9z3hu6m07vxpukz1cz3" caption="Content form" />

Editors will be able to select a product whose information lives in the remote source by using a dropdown menu directly in the content form.

## Useful links

- [Remote data:](/docs/developer-guides/remote-data/overview) Check out our remote data guides to learn more about Remote Sources & Remote Fields.
- [References:](/docs/developer-guides/schema/references) Learn more about the different reference field types and how to configure them.

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>



---
# Related product pages

Source: https://hygraph.com/docs/recipes/product-page/product-pages-connected

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

![Product Page model - Book](/images/docs/recipes/product-page/connectedmodels-book-model.png)

This guide shows how to create interconnected Product models for an online bookstore with Product information stored in the CMS.

Whether you decide to use an external PIM as the source of truth for your product information and copy/paste the information in Hygraph or create and store all of your product information in the CMS only, this recipe shows an efficient way to combine schema elements to create a set of connected product pages that contain basic product information about books, authors, and genres, and use reference fields to allow users to navigate the linked data.

This mock image shows what a frontend using this setup could look like:

![Product Page mock image](/images/docs/recipes/product-page/mock-image-bookstore.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. [Look into the following section to learn more about your options.](/docs/recipes/product-page/product-pages-connected#what-you-can-do)

### What you can do

Use this guide to create a **Product Page** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/product-page/section-index#product-pages-cookbook)

This is the way to go if you're curious about how we built the Product Pages but don't want to follow the step-by-step creation process. This project contains the entire **Product Page Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Product Page model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Component**: a predefined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **Basic component field**: a component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one or allow multiple component instances to be added to the content entry.
- **Enumerations:** an enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="w32gI7jLizE" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the enumeration

![Create the enumeration](/images/docs/recipes/product-page/connectedmodels-enumeration.png)

One of the Product Page models that you'll create in the next section will contain a component field with a dropdown menu for product discounts. Since it's best to start building from the bottom up, we'll start with the enumeration.

Navigate to the **Schema builder** of your Hygraph project, and click `+Add` next to **Enumerations** on the left sidebar. We'll use the following information to create the first one:

| Field        | Input                                      |
| ------------ | ------------------------------------------ |
| Display name | Discount                                   |
| API ID       | Discount                                   |
| Description  | Use the dropdown menu to select a discount |

Before saving, you need to add enumeration values, which are the options you will get when using this later as a dropdown menu in the content form.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID     |
| ------------ | ---------- |
| Discount 10% | discount10 |
| Discount 20% | discount20 |
| Discount 30% | discount30 |
| Discount 40% | discount40 |
| Discount 50% | discount50 |

Finally, click `Add enumeration` to save.

<Alert theme="info" title="Pro Tip">
Adding the possible discounts as an enumeration ensures editors can only select one of the predefined values. Alternatively, you could use a `Float` field. This would allow editors to write down a number of their choice.

The field type you want to select for something like a discount will depend on how much freedom you want to give to your editors. While the `Float` field would allow more flexibility, the `Enumeration` field reduces the possibility of error.
</Alert>

Now that you have created the enumeration that you need to add to your component, it's time to create the component.

### 2. Create the component

![Create the component](/images/docs/recipes/product-page/connectedmodels-component.png)

In this section you'll create a component for promotional prices, which you will later add to one of your models as a component field. Creating this as a component offers the possibility to easily reuse it in different models as your business grows.

In the **Schema builder**, click `+Add` next to **Components** and use the following information:

| Field         | Input               |
| ------------- | ------------------- |
| Display name  | Promotion component |
| API ID        | PromotionComponent  |
| API ID Plural | PromotionComponents |

Click `Add component` to save.

Now that you've created the component itself, it's time to add fields to it. This component will have a name, a description, an image, and the enumeration for discounts that you created in the previous step.

We'll start with the discount name. Find the `Single line text` field on the right sidebar, click `Add`, and use the following information to create it:

| Tab      | Field                | Input                                       |
| -------- | -------------------- | ------------------------------------------- |
| Settings | Display name         | Promotion name                              |
| Settings | API ID               | promotionName                               |
| Settings | Description          | Write a name to identify the promotion here |
| Settings | `Use as title field` | Leave this checkbox selected                |

Click `Add` to save.

Next, add the discounts list. Find the `Enumeration` field on the right sidebar, click `Add`, and use the following information to create it:

| Tab         | Field                 | Input                                       |
| ----------- | --------------------- | ------------------------------------------- |
| Settings    | Display name          | Promotion discount                          |
| Settings    | API ID                | promotionDiscount                           |
| Settings    | Enumeration           | Use the dropdown menu to select `Discount`. |
| Settings    | Description           | Use the list to select a discount           |
| Validations | `Make field required` | Select this checkbox                        |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">
We are making this field required, because the actual discount value is the only one that's absolutely necessary if you want to give a discount on a product.

The rest of the fields will be optional in this example, but you can choose to make them required if it works best for your company's workflow.
</Alert>

Next, you want the component to offer the option to add a description by including a rich text field, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input                                    |
| -------- | ------------ | ---------------------------------------- |
| Settings | Display name | Promotion description                    |
| Settings | API ID       | promotionDescription                     |
| Settings | Description  | You can add a promotion description here |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">
In this case, we are not enabling embedding for the rich text field because we haven't created the models yet.

Keep in mind that if you want to be able to link content from any of your models in this rich text field, you can come back to edit this field later and add them.

A possible use in the context of this example would be to have a discount an all books from the same author, and in that case you could embed some of the author's books in the promotion description.
</Alert>

Finally, you want editors to optionally include one image related to the discount in the content form. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field        | Input                     |
| -------- | ------------ | ------------------------- |
| Settings | Display name | Discount image            |
| Settings | API ID       | discountImage             |
| Settings | Description  | You can add an image here |

Click `Add` to save.

### 3. Create the models

Now it's time to create the models. We'll create one for authors, one for books and one for book genres.

Keep in mind that this setup contemplates information being stored in the CMS, so we'll include all the information needed to create a book listing, an author page, and genres as categories. This, however, does not necessarily mean this information exists *only* in the CMS, as it could be copy-pasted from an external source that a company uses to store their product information.

<Alert theme="info" title="Pro Tip">
There is no one-size-fits-all for all possible product model configurations, so when you create your own product page model, remember to give some serious thought to what you'll be selling. 

Study what information a potential buyer would need to buy the product, as well as what information a developer would need to create a frontend for you product listings.
</Alert>

#### Book model

![Product Page model - Book](/images/docs/recipes/product-page/connectedmodels-book-model.png)

You'll create the Book model first. In the **Schema builder**, click `+Add` next to `Models`, and use the following information:

| Field         | Input            |
| ------------- | ---------------- |
| Display name  | Bookstore - Book |
| API ID        | BookstoreBook    |
| API ID Plural | BookstoreBooks   |

Click `Add Model` to save.

<Alert theme="info">
We are naming the model “Bookstore - Book” to make it easy to identify in the cookbook project, which contains more than one recipe. The rest of the models that belong in this recipe will also be named “Bookstore - (…)”.
</Alert>

Book listings in online stores normally show the title, ISBN, a summary, a cover image, and the price. In addition to this, the model will have a a boolean to indicate if the book is in stock, and the promotion component that you built earlier.

<Alert theme="info">
We will also link this model to the other two using reference fields, but we will do this at the end of the process since we need to create all models first.
</Alert>

You'll start with the book title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                            |
| ----------- | --------------------- | -------------------------------- |
| Settings    | Display name          | Book title                       |
| Settings    | API ID                | bookTitle                        |
| Settings    | Description           | Write the title of the book here |
| Settings    | `Use as title field`  | Leave this checkbox selected     |
| Validations | `Make field required` | Select this checkbox             |

Click `Add` to save.

This configuration prevents editors from creating book listings without a title.

Next, you'll add the ISBN. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                  |
| ----------- | --------------------- | ---------------------- |
| Settings    | Display name          | ISBN                   |
| Settings    | API ID                | isbn                   |
| Settings    | Description           | Add the book ISBN here |
| Validations | `Make field required` | Select this checkbox   |
| Validations | `Set field as unique` | Select this checkbox   |

Click `Add` to save.

Since an ISBN is essentially a product identifier, we decided to make it unique. You can later use it to find a specific book in your content entries.

Next, you want editors to be able to add an image of the book cover. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field        | Input                               |
| -------- | ------------ | ----------------------------------- |
| Settings | Display name | Cover image                         |
| Settings | API ID       | coverImage                          |
| Settings | Description  | Add an image of the book cover here |

Click `Add` to save.

Next, you want editors to add a book summary. We'll use a rich text field for this, as it also allows some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input                             |
| -------- | ------------ | --------------------------------- |
| Settings | Display name | Summary                           |
| Settings | API ID       | summary                           |
| Settings | Description  | You can add the book summary here |

Click `Add` to save.

Now you'll add a switch that editors can use to indicate whether the book is in stock. Add a `Boolean` field from the right sidebar, using the following information:

| Tab | Field | Input |
| --- | --- | --- |
| Settings | Display name | Is available |
| Settings | API ID | isAvailable |
| Settings | Description | Select this switch to indicate that a book is available, and deselect it to indicate that it's not. |

Click `Add` to save.

A smart way to give this boolean an additional use, is to use it to set a condition. For instance, imagine you want the price field of the book to **only** show when the book is available. To do this, add a `Float` field from the right sidebar, using the following information:

| Tab      | Field                  | Input                                                                                                                 |
| -------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Settings | Display name           | Price                                                                                                                 |
| Settings | API ID                 | price                                                                                                                 |
| Settings | Description            | Add the book price here                                                                                               |
| Advanced | Conditional visibility | Select the `Show based on condition` checkbox, and under “**Show this field if”**, select `is available` `is` `true`. |

Click `Add` to save.

The conditional visibility you set for this field means that if the `Is available` boolean that you created in the previous step is selected, then this price field will be visible in the content form. This is handy considering that prices can change when the company buys new stock.

It's time to add the **Promotion** component that you built earlier. Add a `Basic component` field from the right sidebar, using the following information:

| Tab      | Field              | Input                                             |
| -------- | ------------------ | ------------------------------------------------- |
| Settings | Display name       | Promotion                                         |
| Settings | API ID             | promotion                                         |
| Settings | Description        | You can add a promotion here                      |
| Settings | Select a component | Use the dropdown to select `Promotion component`. |

Click `Add` to save.

Your model is ready for now. We'll be coming back later, after creating all models, to connect them.

#### Author model

![Product Page model - Author](/images/docs/recipes/product-page/connectedmodels-author-model.png)

Since the objective of an online bookstore is to sell books, it would be natural for the **Book** model to contain the most information. However, it is also common for online bookstores to allow potential buyers to navigate by author and genre. In our example, these will only contain basic information, as the real aim is not to provide in-depth information about an author or a certain literary genre, but rather to facilitate navigation.

This Author model will be a simple model containing only the author's name, bio & photograph. After you're done creating all models, you will revisit this model as well, to connect it to the others using reference fields.

In the **Schema builder**, click `+Add` next to `Models`, and use the following information:

| Field         | Input              |
| ------------- | ------------------ |
| Display name  | Bookstore - Author |
| API ID        | BookstoreAuthor    |
| API ID Plural | BookstoreAuthors   |

Click `Add Model` to save. Let's add the fields next.

You'll start with the name. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Name                         |
| Settings    | API ID                | name                         |
| Settings    | Description           | Write the author's name here |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |

Click `Add` to save.

This configuration prevents editors from creating author entries without a title (name).

Next, you want editors to add a bio for each author. We'll use a rich text field for this, as it also allows some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input                  |
| -------- | ------------ | ---------------------- |
| Settings | Display name | Biography              |
| Settings | API ID       | biography              |
| Settings | Description  | You can add a bio here |

Click `Add` to save.

Next, you want editors to be able to add a picture of the author. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field        | Input                      |
| -------- | ------------ | -------------------------- |
| Settings | Display name | Author photo               |
| Settings | API ID       | authorPhoto                |
| Settings | Description  | You can add a picture here |

Click `Add` to save.

We'll come back to this model later. Let's move on to create the final model.

#### Genre model

![Product Page model - Genre](/images/docs/recipes/product-page/connectedmodels-genre-model.png)

This model will be the simplest of the group. It will only contain a name and a description. Practically speaking, this will work as a category model.

In the **Schema builder**, click `+Add` next to `Models`, and use the following information:

| Field         | Input             |
| ------------- | ----------------- |
| Display name  | Bookstore - Genre |
| API ID        | BookstoreGenre    |
| API ID Plural | BookstoreGenres   |

Click `Add Model` to save. Let's add the fields next.

Let's start with the genre name. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Name                         |
| Settings    | API ID                | name                         |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validation  | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration prevents editors from creating genre entries without a name, or to create two or more entries with the same genre name.

Finally, you want genres to have a description, in case editors are unsure which ones to select for a certain book or author. We'll use a rich text field for this, as it also allows some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input                                |
| -------- | ------------ | ------------------------------------ |
| Settings | Display name | Description                          |
| Settings | API ID       | description                          |
| Settings | Description  | You can add a genre description here |

Click `Add` to save.

It is now time to connect the models. We'll work on this in the next step.

### 4. Connect the models

Now that the three models have been created, it's time to connect them. To do so, we'll use reference fields. Selecting the reference field configuration your model needs depends on the characteristics of your product. 

In the context of the current example:

- An **author** can have more than one book, and those books can fit into multiple genres.
- A **book** can have multiple authors, and fit into multiple genres.
- A **genre** encompasses a number of books and authors.

With this in mind, the best way to connect these three models is to use two-way references that allow multiple values. Creating two-way references also creates a reverse field in the related model. Because of this, while we need to have 6 reference fields, we will only be creating 3.

You'll create the first reference field in the **Book** model. Access it in the **Schema builder**, find the reference field on the right sidebar, and click **Add**. Use the following information:

| Tab           | Field                                          | Input                                              |
| ------------- | ---------------------------------------------- | -------------------------------------------------- |
| Define        | `Allow only one model to be referenced`        | Select this radio button.                          |
| Define        | Model to reference                             | use the dropdown to select `Bookstore - Author`    |
| Define        | Reference direction                            | Use the radio button to select `Two-way reference` |
| Define        | Relation cardinality                           | Many to many                                       |
| Define        | `Allow multiple (model name) per (model name)` | Select **both** checkboxes                         |
| Configure     | Display name                                   | Author                                             |
| Configure     | API ID                                         | author                                             |
| Configure     | Description                                    | Select the author or authors of the book           |
| Reverse field | Display name                                   | Books                                              |
| Reverse field | API ID                                         | Books                                              |
| Reverse field | Description                                    | Add books by this author here                      |

Click `Add` to save.

This reference configuration will allow editors to add links to multiple books to author entries, and multiple authors to book entries. If you check the **Author** model, you'll find the **Books** reverse field has been added there.

Repeat the process to add a reference field that links to the **Genre** model using the following information:

| Tab           | Field                                          | Input                                              |
| ------------- | ---------------------------------------------- | -------------------------------------------------- |
| Define        | `Allow only one model to be referenced`        | Select this radio button.                          |
| Define        | Model to reference                             | use the dropdown to select `Bookstore - Genre`     |
| Define        | Reference direction                            | Use the radio button to select `Two-way reference` |
| Define        | Relation cardinality                           | Many to many                                       |
| Define        | `Allow multiple (model name) per (model name)` | Select **both** checkboxes                         |
| Configure     | Display name                                   | Genre                                              |
| Configure     | API ID                                         | genre                                              |
| Configure     | Description                                    | Select one of more genres this book fits into      |
| Reverse field | Display name                                   | Books                                              |
| Reverse field | API ID                                         | Books                                              |
| Reverse field | Description                                    | Add books that fit this genre here                 |

Click `Add` to save.

By now, despite having created only 2 reference field, we have the 2 that we added to the **Book** model, a reverse field in the **Author** model, and one in the **Genre** model.

Navigate to the Author model. We said earlier that an author can write several books that may fit into different genres. While we already have a reference field here which will allow editors to link multiple book entries, we're missing a reference to the **Genre** model.

Repeat the process one more time to add a reference field that links to the **Genre** model using the following information:

| Tab           | Field                                          | Input                                                 |
| ------------- | ---------------------------------------------- | ----------------------------------------------------- |
| Define        | `Allow only one model to be referenced`        | Select this radio button.                             |
| Define        | Model to reference                             | use the dropdown to select `Bookstore - Genre`        |
| Define        | Reference direction                            | Use the radio button to select `Two-way reference`    |
| Define        | Relation cardinality                           | Many to many                                          |
| Define        | `Allow multiple (model name) per (model name)` | Select **both** checkboxes                            |
| Configure     | Display name                                   | Genre                                                 |
| Configure     | API ID                                         | genre                                                 |
| Configure     | Description                                    | Select one or more genres this author wrote books for |
| Reverse field | Display name                                   | Authors                                               |
| Reverse field | API ID                                         | authors                                               |
| Reverse field | Description                                    | Select authors whose work fits this genre             |

Click `Add` to save.

You have now created the last 2 reference fields that we needed, since one was created here and its reverse field in the linked model (Genre).

This setup shows 3 content models for an online bookstore. As they are all connected through references, every time an editor creates a new content entry for a book, they will have the chance to either create new entries for genre & author, or link existing ones.

A frontend using this data could allow navigating all three to find related information, i.e. click on an author name to find all the books by that author that are available.

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9v2jatt07w5kcf364mb" caption="Content form" />

Editors will be able to create product entries, and at the same time link existing entries from the related models or create new ones.

## Useful links

- [Components documentation:](/docs/developer-guides/schema/components) Learn more about components, available component field types, and how to use them.
- [Enumerations:](/docs/developer-guides/schema/using-enumerations) Learn more about enumerations and how to configure them.
- [References:](/docs/developer-guides/schema/references) Learn more about the different reference field types and how to configure them.

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

---
# Product Page overview

Source: https://hygraph.com/docs/recipes/product-page/section-index

## Overview

In this section, you will find recipes that you can use to create **Product Page models** using different field configurations.

| Recipe                                                                                   | Description                                                                                                                                    |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [Product Page eCommerce](/docs/recipes/product-page/product-page-ecommerce)              | This guide shows how to create a Product model for eCommerce with Product information stored in the CMS.                                       |
| [Product Page with Akeneo app](/docs/recipes/product-page/product-page-akeneo)           | This guide shows how to create a Product model in Hygraph that fetches product information from an external PIM (Akeneo) via app integrations. |
| [Product Page with Remote Source](/docs/recipes/product-page/product-page-remote-source) | This guide shows how to create a Product model in Hygraph that fetches product information from an external PIM via Remote Sources.            |
| [Related Product Pages](/docs/recipes/product-page/product-pages-connected)              | This guide shows how to create interconnected Product models for an online bookstore with Product information stored in the CMS.               |

## Product pages cookbook

Cloning the entire cookbook is a great option if you're curious about the content of the Product Pages but don't want to follow the step-by-step creation process. 

<Button
  href="https://app.hygraph.com/clone/3b9f0e97384d4808a23cb4acd8f0e7ce?name=Hygraph%20Recipes%20-%20Product%20Page"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This clonable project contains the entire **Product Page Cookbook**, so you can compare recipes or examine their contents.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

## Apps in your cloned Hygraph Recipes project

Some **Product Page Recipes** rely on apps to fetch and manage product data. When you clone an environment, any installed apps—such as Remote Data Apps and the Akeneo App—are copied along with it.
- Remote data apps will work immediately without requiring additional setup.
- The **Akeneo** App requires re-entering your own Akeneo secret keys for authentication. To do this, go to the **Apps** section in Hygraph, find the Akeneo app card, click `Edit`, and update the credentials with the keys from your Akeneo account.

Once configured, the apps will function just as they did in the original project!

---
# Flat taxonomy model

Source: https://hygraph.com/docs/recipes/taxonomy/flat-taxonomy

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create a flat taxonomy model that connects content entries to categories.

You'll create a category model and reference it in another model to select content entries as categories.

![Flat taxonomy model](/images/docs/recipes/taxonomy/flat-taxonomy-model.png)

This recipe is a great option if you need a taxonomy setup that is fast & simple to use. It is also a good setup to use if your project works with flat categories that do not require to be connected in a way that establishes a hierarchy.

<Alert theme="info">

[Taxonomies](/docs/developer-guides/schema/taxonomies) are now available in Hygraph. This eliminates the need for any manual configuration, and simplifies content organization and ensures consistency across your schema. Contact our sales team for access.
</Alert>

This image shows what a frontend using this setup could look like:

![Flat taxonomy - frontend visual example](/images/docs/recipes/taxonomy/flat-taxonomy-model-example.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Flat taxonomy** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/taxonomy/section-index#taxonomy-cookbook)

This is the way to go if you're curious about how we built the taxonomy recipes but don't want to follow the step-by-step creation process. This project contains the entire **Taxonomy Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Flat taxonomy model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="jIBCNDaQDZ8" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the category model

This model will let you create categories as content entries. For the sake of this example, we will only include a couple of fields to store basic information, but you may want to add more fields depending on your needs.

To create the model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                 |
| ------------- | --------------------- |
| Display name  | Category - Book Genre |
| API ID        | CategoryBookGenre     |
| API ID Plural | CategoryBookGenres    |

Click `Add Model` to save.

Let's add fields to this model. We will add a `Single line text` field to use as category name, and a `Rich Text` field for the category description.

For the category name, add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Category name                |
| Settings    | API ID                | categoryName                 |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures all entries are created with the category names as titles, for quick identification in the content table. These titles must also be unique, which will contribute to a good user experience for editors selecting categories for a content entry.

Next, you want to include a rich text field for the description, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                |
| ----------- | --------------------- | -------------------- |
| Settings    | Display name          | Category description |
| Settings    | API ID                | categoryDescription  |
| Validations | `Make field required` | Select this checkbox |

Click `Add` to save.

We created a model for the categories because creating categories as content entries means they can be easily referenced in other models and components later on. This setup also makes adding new categories or editing existing ones very easy.

In the next step, we will create the **Flat Taxonomy model** with a reference field that links this model.

### 2. Create the final model

For this example, we'll create a model that contains some basic book data, and allows selecting literary genres as book categories.

This simplified example focuses on linking categories, so make sure to carefully think what other fields your model might need when working on a flat taxonomy setup for your own project.

To create this model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input               |
| ------------- | ------------------- |
| Display name  | Flat Taxonomy Model |
| API ID        | FlatTaxonomyModel   |
| API ID Plural | FlatTaxonomyModels  |

Click `Add Model` to save.

This model will contain a `Single line text` field for the book title, a `Rich Text` field for the book description, an `Asset picker` field to add book related images, and a `Reference` field to link categories.

First, we'll add the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Book Title                   |
| Settings    | API ID                | bookTitle                    |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all book entries contain a title that will allow easy identification in the content table.

Next, you want to include a rich text field for the description, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input            |
| -------- | ------------ | ---------------- |
| Settings | Display name | Book Description |
| Settings | API ID       | bookDescription  |

Click `Add` to save.

Next, you want editors to be able to include at least one image in the content form when writing about books. Add an `Asset picker` field from the right sidebar, using the following information:

| Tab      | Field                   | Input                                    |
| -------- | ----------------------- | ---------------------------------------- |
| Settings | Display name            | Image                                    |
| Settings | API ID                  | image                                    |
| Settings | Description             | Add one or more images for the book here |
| Settings | `Allow multiple assets` | Select this checkbox                     |

Click `Add` to save.

Finally, we will add a reference field that connects the model we created in the previous step. Referencing the category model here will allow editors to quickly link category content entries directly from the content form.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                              |
| --------- | --------------------------------------- | -------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                          |
| Define    | Model to reference                      | use the dropdown to select `Category - Book Genre` |
| Define    | Reference direction                     | Use the radio button to select `One-way reference` |
| Define    | Relation cardinality                    | One to Many                                        |
| Define    | `Allow multiple (…)`                    | Select this checkbox                               |
| Configure | Display name                            | Genre                                              |
| Configure | API ID                                  | genre                                              |
| Configure | Description                             | Select one or more literary genres                 |

Click `Add` to save.

Your model is ready! This is how you build a flat taxonomy model in Hygraph. Our [Related product pages](/docs/recipes/product-page/product-pages-connected) recipe uses models and references in a similar way to connect 3 models and potentially allow the user to navigate an online bookstore by genre, books and authors. Make sure to check it out if you're looking for a flat taxonomy setup that's a bit more complex than this one.

You could make a bit more out of this by adding an additional reference field with the same configuration to add a subcategory, and allowing your frontend to handle the hierarchy using the field IDs.

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xa13hu6u07vxdmemr6qc" caption="Resulting content form" />

Editors will be able to easily link categories using a reference field. Since our reference field allows multiple values, they will be able to select more than one.

## Useful links

- [**References documentation**](/docs/developer-guides/schema/references)


---
# Taxonomy overview

Source: https://hygraph.com/docs/recipes/taxonomy/section-index

This section contains recipes for creating taxonomy models with different field configurations.

| Recipe                                                                | Description                                                                                                                                         |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Flat Taxonomy model](/docs/recipes/taxonomy/flat-taxonomy)           | Learn how to create a flat taxonomy model.                                                                                                          |
| [Two-level taxonomy model](/docs/recipes/taxonomy/two-level-taxonomy) | Learn how to create a two-level taxonomy model that lets you select parent categories that displays reference fields to add related sub-categories. |

<Alert theme="info">

[Taxonomies](/docs/developer-guides/schema/taxonomies) are now available in Hygraph. This eliminates the need for any manual configuration, and simplifies content organization and ensures consistency across your schema. Contact our sales team for access.
</Alert>

## Taxonomy cookbook

Cloning the entire cookbook is a great option if you're curious about the content of the taxonomy models but don't want to follow the step-by-step creation process.

<Button
  href="https://app.hygraph.com/clone/a9b6e005201a438386a060f0fcb6f3a9?name=Hygraph%20Recipes%20-%20Taxonomy"
  size="md"
  variant="outlined"
  theme="primary"
  iconRight="ArrowRight"
  targetBlank
>Clone this project</Button>

This cloneable project contains the entire **Taxonomy Cookbook**, so you can compare recipes or examine their contents.

Keep in mind that if you clone the cookbook and then attempt to go over the tutorial for a certain recipe, the screens might not look exactly the same, as the cookbook contents reflect multiple recipes.

<Alert theme="info">

- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)

</Alert>


---
# Two-level taxonomy model

Source: https://hygraph.com/docs/recipes/taxonomy/two-level-taxonomy

## Overview

<Alert theme="success" title="Do you have suggestions?">
<Link href="https://hygraph-community.slack.com" target="_blank">Join our community</Link> to suggest new recipe ideas!
</Alert>

This guide shows how to create a two-level taxonomy model that lets you select parent categories that display reference fields to add related sub-categories.

You'll create an enumeration for the parent categories, two sub-category models, a category selector component, and a final sample model for a drinks page that lets you add some basic information about the drink, and select parent categories and sub-categories for it.

![Two-level taxonomy model](/images/docs/recipes/taxonomy/two-level-taxonomy-model.png)

This recipe is a great option if you need a taxonomy setup that allows referencing sub-category entries based on the parent category selected. A setup like this ensures that after selecting a parent category, editors will only be able to reference sub-categories related to it.

<Alert theme="info">

[Taxonomies](/docs/developer-guides/schema/taxonomies) are now available in Hygraph. This eliminates the need for any manual configuration, and simplifies content organization and ensures consistency across your schema. Contact our sales team for access.
</Alert>

This image shows what a frontend using this setup could look like:

![Two-level taxonomy - frontend visual example](/images/docs/recipes/taxonomy/two-level-taxonomy-model-example.png)

## Prerequisites

- `REQUIRED:` You need to have a Hygraph account. If you don't have one, <Link href="https://app.hygraph.com/signup" target="_blank"><strong>you can sign up here.</strong></Link>
- `REQUIRED:` You need to have a Hygraph project. Look into the following section to learn more about your options.

### What you can do

Use this guide to create a **Two-level taxonomy** model. You have two options:

- `OPTION 1:` [**Create a project.**](/docs/getting-started/fundamentals/quickstart#create-a-project) This is the way to go if you want to follow the entire tutorial for learning purposes.
- `OPTION 2:` **Use an existing project of yours.** This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.

<Alert theme="info">
- Take <Link href="https://hygraph.com/pricing" target="_blank"><strong>plan limits</strong></Link> into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our [**Getting Started Tutorial!**](/docs/getting-started/onboarding-overview)
</Alert>

#### Not in the mood to start building?

[**Clone the entire cookbook**](/docs/recipes/taxonomy/section-index#taxonomy-cookbook)

This is the way to go if you're curious about how we built the taxonomy recipes but don't want to follow the step-by-step creation process. This project contains the entire **Taxonomy Cookbook** so you can compare recipes or look into what instances they contain.

## Core concepts

In this guide, you'll work with different schema elements to create a **Two-level taxonomy model**. Let's look into them:

- **Model:** Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- **Enumerations:** an enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
- **Component**: a pre-defined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- **Basic component field**: A component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A **basic component field** can only have one component attached to it. You can limit the number of component instances to one or allow multiple component instances to be added to the content entry.
- **References:** 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 create related content directly from the content form.

## Step-by-step guide

<VideoEmbed videoId="dALBVJe261o" />

This video follows the same step-by-step tutorial offered in this document.

### 1. Create the enumeration

Our two-level taxonomy model will contain an enumeration field to select a drink type.

Navigate to the **Schema builder** of your Hygraph project, and click `+Add` next to **Enumerations** on the left sidebar. We'll use the following information to create the first one:

| Field        | Input  |
| ------------ | ------ |
| Display name | Drinks |
| API ID       | Drinks |

The next step is to add enumeration values, which are the options you will get when using this later as a dropdown menu.

For every enumeration value, you need to enter a `Display name`, an `API ID`, and click `Add`.

We'll add the following values:

| Display name | API ID |
| ------------ | ------ |
| Wine         | wine   |
| Juice        | juice  |

Finally, click `Add enumeration` to save.

We've only added two values because the next step involves creating one model for each of the values that we created here, and we don't want you to waste time creating endless models that would not add quality to the current example.

Since the focus of this guide is the taxonomy, what matters the most is the dynamic where we use an enumeration field to set conditional visibility for reference fields linking the models we will create next.

### 2. Create the sub-category models

We will create two models for our sub-categories. For the sake of this example, we will only include a couple of fields to store basic information, but you may want to add more fields depending on your needs.

To create the first model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input        |
| ------------- | ------------ |
| Display name  | Drink - Wine |
| API ID        | DrinkWine    |
| API ID Plural | DrinkWines   |

Click `Add Model` to save.

Let's add fields to this model. We will add a `Single line text` field to use as category name, and a `Rich Text` field for the category description.

For the category name, add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Name                         |
| Settings    | API ID                | name                         |
| Settings    | Description           | Add a name here              |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures all category entries are created with the names as titles, for quick identification in the content table. These titles must also be unique, which will avoid editors adding the wrong entry when selecting categories.

Next, you want include a rich text field for the description, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab         | Field                 | Input                    |
| ----------- | --------------------- | ------------------------ |
| Settings    | Display name          | Description              |
| Settings    | API ID                | description              |
| Settings    | Description           | Write a description here |
| Validations | `Make field required` | Select this checkbox     |

Click `Add` to save.

We created a model for the categories because creating categories as content entries means they can be easily referenced in other models and components later on. This setup also makes adding new categories or editing existing ones very easy.

Since our second category model will contain the same set of fields, we will go ahead and duplicate the model that we've just created, and then edit its details.

In the **Drink - Wine** model, click the 3 dots context menu at the top of the screen, and select `Duplicate`.

![Duplicate model](/images/docs/recipes/taxonomy/duplicate-category-model.png)

The system will duplicate the model and will rename it to **Copy of (model name).**

Click on the `Settings` tab at the top and replace the existing information with the following:

| Field         | Input         |
| ------------- | ------------- |
| Display name  | Drink - Juice |
| API ID        | DrinkJuice    |
| API ID Plural | DrinkJuices   |

Click `Update Model` to save.

In the next step, we will create a component for category selection that uses what we've built so far.

### 3. Create the component

In this section you'll create a component for category selection, that we'll later include in the final model as a basic component field.

<Alert theme="info" title="Pro Tip">

Creating a component for the two-level taxonomy setup, allows you potentially reuse it in multiple models.

Since the different levels of category selection would exist at the same level in the schema if added to a model directly, this setup also helps when querying the data, as the query would clearly show these fields as part of the category selection component.

</Alert>

In the **Schema builder**, click `+Add` next to **Components** and use the following information:

| Field         | Input                        |
| ------------- | ---------------------------- |
| Display name  | Two-level taxonomy component |
| API ID        | TwoLevelTaxonomyComponent    |
| API ID Plural | TwoLevelTaxonomyComponents   |

Click `Add component` to save.

Now that you've created the component itself, it's time to add fields to it. You'll add an enumeration field using the enumeration you built earlier, and two reference fields that link to the models you created in the previous step.

This simplified example focuses on linking categories, so make sure to carefully think what other fields your component might need when working on a taxonomy setup for your own project.

Find the `Enumeration` field on the right sidebar, click `Add`, and use the following information to create the enumeration:

| Tab      | Field        | Input                                     |
| -------- | ------------ | ----------------------------------------- |
| Settings | Display name | Drink selector                            |
| Settings | API ID       | drinkSelector                             |
| Settings | Enumeration  | Use the dropdown menu to select `Drinks`. |
| Settings | Description  | Select a drink from the menu              |

Click `Add` to save.

<Alert theme="info" title="Pro Tip">

For the purpose of this example, we're not allowing multiple values. If your category selection requires more than one parent category being selected at the same time, consider allowing multiple values here.

</Alert>

This enumeration field will allow us to set conditions for the 2 reference fields we're about to add. **We did not make this field required because conditional visibility does not support required fields.**

Finally, we will add two reference fields that connect the models we created in the previous step. Referencing the category models here will allow editors to quickly link category content entries directly from the content form.

Add a `Reference` field from the right sidebar, using the following information:

| Tab       | Field                                   | Input                                                                               |
| --------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                           |
| Define    | Model to reference                      | use the dropdown to select `Drink - Wine`                                           |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                  |
| Define    | Relation cardinality                    | One to Many                                                                         |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                |
| Configure | Display name                            | Wine                                                                                |
| Configure | API ID                                  | wine                                                                                |
| Configure | Description                             | Select one or more types of wine                                                    |
| Configure | Show based on condition                 | Select this checkbox and then use the dropdowns to select `Drink selector is Wine.` |

Click `Add` to save.

We'll repeat the process to add the final reference, using the following information:

| Tab       | Field                                   | Input                                                                                |
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| Define    | `Allow only one model to be referenced` | Select this radio button.                                                            |
| Define    | Model to reference                      | use the dropdown to select `Drink - Juice`                                           |
| Define    | Reference direction                     | Use the radio button to select `One-way reference`                                   |
| Define    | Relation cardinality                    | One to Many                                                                          |
| Define    | `Allow multiple (…)`                    | Select this checkbox                                                                 |
| Configure | Display name                            | Juice                                                                                |
| Configure | API ID                                  | juice                                                                                |
| Configure | Description                             | Select one or more types of juice                                                    |
| Configure | Show based on condition                 | Select this checkbox and then use the dropdowns to select `Drink selector is Juice.` |

Click `Add` to save.

In the next step, we will create the **Two-level Taxonomy model**, which will contain a couple of basic information fields and a basic component field for the component we've just created.

### 2. Create the final model

For this example, we'll create a basic model for a drinks page. We'll add a drink name & description, and a component field for category selection.

To create this model, navigate to the **Schema builder** and click `+Add` next to **Models**. Use the following information:

| Field         | Input                    |
| ------------- | ------------------------ |
| Display name  | Two-level Taxonomy Model |
| API ID        | TwoLevelTaxonomyModel    |
| API ID Plural | TwoLevelTaxonomyModels   |

Click `Add Model` to save.

This model will contain a `Single line text` field for the drink name, a `Rich Text` field for the drink description, and a `Basic component` field for category selection.

First, we'll add the title. Add a `Single line text` field from the right sidebar, and use the following information:

| Tab         | Field                 | Input                        |
| ----------- | --------------------- | ---------------------------- |
| Settings    | Display name          | Drink name                   |
| Settings    | API ID                | drinkName                    |
| Settings    | `Use as title field`  | Leave this checkbox selected |
| Validations | `Make field required` | Select this checkbox         |
| Validations | `Set field as unique` | Select this checkbox         |

Click `Add` to save.

This configuration ensures that all the resulting content entries contain a unique title that will allow easy identification in the content table.

Next, you want to include a rich text field for the description, which will also allow some formatting. Add a `Rich text` field from the right sidebar, using the following information:

| Tab      | Field        | Input       |
| -------- | ------------ | ----------- |
| Settings | Display name | Description |
| Settings | API ID       | description |

Click `Add` to save.

Next, you will add the basic component field.  Find the `Basic component` field on the right sidebar, using the following information:

| Tab      | Field              | Input                                                      |
| -------- | ------------------ | ---------------------------------------------------------- |
| Settings | Display name       | Category selector                                          |
| Settings | API ID             | categorySelector                                           |
| Settings | Description        | Select a category and subcategories                        |
| Settings | Select a component | Use the dropdown to select `Two-level taxonomy component`. |

Click `Add` to save.

Your model is ready! This is how you build a two-level taxonomy model in Hygraph where the sub-categories that editors can select are tied to the parent category.

## Resulting content form

If you followed this tutorial, your resulting content form should look like this:

<VideoBlock src="https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9xa2yjau307w5ekz6486x" caption="Resulting content form" />

When using the category selection component, editors will be able to use a dropdown menu to select a parent category, which will determine which reference field will display to select sub-categories.

In this example, the editor creates a content entry about orange juice and when selecting categories for the drink, they select that it’s a juice of the citrus variety.

## Useful links

- [Components documentation:](/docs/developer-guides/schema/components) Learn more about components, available component field types, and how to use them.
- [Enumerations:](/docs/developer-guides/schema/using-enumerations) Learn more about enumerations and how to configure them.
- [References:](/docs/developer-guides/schema/references) Learn more about the different reference field types and how to configure them.


---
# Additional types API reference

Source: https://hygraph.com/docs/app-framework/api-reference/api-reference-additional-types

## Model

```ts
interface Model {
  apiId: string;
  apiIdPlural: string;
  id: string;
  description: string | null;
  displayName: string;
  isLocalized: boolean;
  // Function to get all fields of current model.
  getFields: () => Promise<Array<{
    id: string,
    apiId: string,
    displayName: string,
    [key:string]: any,    
  }>>
}
```

## Form

```ts
interface Form {
  change: <Value = any>(name: string, value: Value) => Promise<void>;
  changeBulk: (values: Record<string, any>) => Promise<void>;
  // @see https://hygraph.com/classic-docs/ui-extensions/react-sdk/state-getters#get-state
  getState: <Values = Record<string, any>>() => Promise<FormState<Values>>;
  // @see https://hygraph.com/classic-docs/ui-extensions/react-sdk/state-getters#get-field-state
  getFieldState: <Value = any>(fieldName: string) => Promise<FieldState<Value>>;
  // @see https://hygraph.com/classic-docs/ui-extensions/react-sdk/state-subscriptions#subscribe-to-field-state
  subscribeToFieldState: <Value = any>(
    name: string,
    callback: (state: FieldState<Value>) => any,
    subscription: FieldSubscription,
  ) => Promise<() => any>;
  // @see https://hygraph.com/classic-docs/ui-extensions/react-sdk/state-subscriptions#subscribe-to-form-state
  subscribeToFormState: <Values = Record<string, any>>(
    callback: Subscriber<FormState<Values>>,
    subscription: FormSubscription,
  ) => Promise<() => any>;
  // @see https://hygraph.com/classic-docs/ui-extensions/field-extension/interacting-with-fields#set-fields-visibility
  setFieldsVisibility: (
    arg:
      | VisibilityMap
      | ((currentVisibilityMap: VisibilityMap) => VisibilityMap),
  ) => void;
}
```

## Locale

```ts
interface Locale {
  apiId: string;
  id: string;
  displayName: string;
  isDefault: boolean;
}
```

## Stage

```ts
interface Stage {
  id: string;
  apiId: string;
  color: string;
  colorPaletteId: keyof typeof StageColorPalette;
  backgroundColor: string;
  displayName: string;
  description?: string | null | undefined;
  isSystem: boolean;
  position: number;
}

export const StageColorPalette = {
  PINK: 'PINK',
  PURPLE: 'PURPLE',
  ORANGE: 'ORANGE',
  RED: 'RED',
  BROWN: 'BROWN',
  TEAL: 'TEAL',
  GREEN: 'GREEN',
  YELLOW: 'YELLOW',
} as const;
```

## User

```ts
interface User {
  id: string;
  kind: keyof typeof UserKind;
  name: string;
  picture: string | null;
  isActive: boolean;
}

export const UserKind = {
  MEMBER: 'MEMBER',
  PAT: 'PAT',
  PUBLIC: 'PUBLIC',
  WEBHOOK: 'WEBHOOK',
} as const;
```

## Dialog

```ts
export type OpenDialog = <
  DialogReturn = any,
  DialogProps = Record<string, any>,
>(
  src: string,
  props?: {
    disableOverlayClick?: boolean;
    maxWidth?: string;
    ariaLabel?: string;
  } & DialogProps,
) => Promise<DialogReturn | null>;
```

## Toasts

```ts
export type ShowToast = (options: ToastOptions) => Promise<Id>;

export type ToastOptions = {
  title: string;
  description?: string;
  variantColor: keyof typeof ToastVariantColor;
  id?: Id;
  isClosable?: boolean;
  position?: keyof typeof ToastPosition;
  duration?: number;
};

type Id = number | string;

export const ToastVariantColor = {
  success: 'success',
  error: 'error',
  warning: 'warning',
  info: 'info',
  primary: 'primary',
  dark: 'dark',
  publish: 'publish',
} as const;

export const ToastPosition = {
  'top-right': 'top-right',
  'top-center': 'top-center',
  'top-left': 'top-left',
  'bottom-right': 'bottom-right',
  'bottom-center': 'bottom-center',
  'bottom-left': 'bottom-left',
} as const;
```


---
# Common props for all elements

Source: https://hygraph.com/docs/app-framework/api-reference/api-reference-common

```ts
export interface ExtensionPropsBase {
  context: {
    project: {
      id: string;
      name: string;
      mgmtApi: string;
    };
    environment: {
      id: string;
      name: string;
      endpoint: string;
      // The app token for the current environment. Available after installation status is set to COMPLETED.
      // Use as a Bearer token to authenticate requests to the Hygraph APIs.
      authToken: string;
    };
  };

  // Opens a separate dialog where you can load data from an external source or create your own UI
  // See `OpenDialog` in "additional types"
  openDialog: OpenDialog;

  // open the asset picker (see the Asset type in your Content Api)
  openAssetPicker: () => Promise<null | (Asset & Record<string, unknown>)>;

  // Function to show Hygraph native toast.
  // See `ShowToast` in "additional types"
  showToast: ShowToast;

  // Reload the current location, as if clicking the Refresh button
  // Useful to update the UI after API calls that might change the form data.
  reloadPage: () => void;

  // Clear all search parameters
  // Useful when app installations add search params that contain state
  // that should be cleared afterwards, such as short-lived tokens.
  clearSearchParams: () => void;
}
```


---
# Field element API reference

Source: https://hygraph.com/docs/app-framework/api-reference/api-reference-field-element

```ts
function useFieldExtension(): FieldExtensionProps;

export interface FieldExtensionProps extends ExtensionPropsBase {
  // name of the field in the form (may differ from the field apiId, ie. for localized fields)
  name: string;

  // current locale on localized field
  locale?: string;

  // id of the current entry, null on a new entry.
  entryId: string | null;

  isTableCell: boolean;

  value: any;

  onBlur: <T extends HTMLElement = HTMLElement>(
    event?: FocusEvent<T>,
  ) => Promise<void>;

  onChange: <T extends HTMLElement = HTMLElement>(
    event: ChangeEvent<T> | any,
  ) => Promise<void>;

  onFocus: <T extends HTMLElement = HTMLElement>(
    event?: FocusEvent<T>,
  ) => Promise<void>;

  // @see https://final-form.org/docs/react-final-form/types/FieldRenderProps
  meta: {
    active: boolean;
    error: any;
    touched: boolean;
  };

  // access to the form state and other form fields
  form: Form;

  // details about the current field
  field: {
    id: string;
    apiId: string;
    description: string | null;
    displayName: string;
    isList: boolean;
    isLocalized?: boolean;
    isRequired?: boolean;
    isUnique?: boolean;
    // true when in version or stage comparison view
    isPreview: boolean;
    type: FieldExtensionType;
  };

  // details about the current model
  model: Model;

  // configuration of the extension.
  extension: {
    config: Record<string, any>;
    fieldConfig: Record<string, any>;
    tableConfig: Record<string, any>;
  };

  // whether the field is currently in fullscreen mode
  isExpanded: boolean;
  // set fullscreen mode
  expand: (expand: boolean | ((isExpanded: boolean) => boolean)) => void;
}
```


---
# Page element API reference

Source: https://hygraph.com/docs/app-framework/api-reference/api-reference-page-element

Page App Elements can use the `useApp` hook to get access to [common props](/docs/app-framework/api-reference/api-reference-common).

```ts
function useApp(): ExtensionPropsBase;
```

You can refer to this example on how to [develop your Page App Element](/docs/app-framework/first-steps/develop-page-element) to learn more about the use of the `useApp` hook in this context.

If you want to see a live example of an app using the Page App Element, check out [Lokalise](/marketplace/apps/hygraph-lokalise-app) for Hygraph.

---
# Sidebar element API reference

Source: https://hygraph.com/docs/app-framework/api-reference/api-reference-sidebar-element

```ts
function useFormSidebarExtension(): FormSidebarExtensionProps;

export interface FormSidebarExtensionProps extends ExtensionPropsBase {
  extension: {
    // global extension config
    config: Record<string, any>;
    // sidebar instance config
    sidebarConfig: Record<string, any>;
  };

  form: Form;
  model: Model;
  allLocales: Locale[];
  stages: Stage[];

  entry?: {
    id: string | null;
    createdBy?: User;
    updatedBy?: User;
    createdAt?: string;
    updatedAt?: string;
  };
}
```


---
# Install an app

Source: https://hygraph.com/docs/app-framework/app-installation

This document will walk you through the process of installing an app on **Hygraph**.

<Alert theme="warning">

The app installation process is similar whether you created the app or it was shared with you. If the app was shared with you or you're installing it from our <Link href="https://hygraph.com/marketplace" target="_blank">Marketplace</Link>, please start from [Step 2](/docs/app-framework/app-installation#2-install-your-app).

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

</Alert>

## 1. Navigate to your apps

![Your apps](/images/docs/app-framework/app-installation/your-apps-menu.png)

If you're a developer and [created an app](/docs/app-framework/first-steps/overview), now you need to install it in order to be able to use it.

Navigate to **You apps** at the top of the project directory, or to **User menu > Your apps** in your Hygraph project, find the card of the app you want to install, then click **Install**.

## 2. Install your app

Whether you got here from step 1, a marketplace link, or a shared app link, the next step is to install the app.

![App installation- DeepL example](/images/docs/app-framework/app-installation/app-installation.png)

To install the app, select a `Project` and an `Environment` from the dropdowns, then click `Install app`.

## 3. App permission authorization

The `App permission authorization` screen will display as a result, where the app requests your authorization to access your project. This screen lists the permissions you'll be granting.

![App permission authorization screen](/images/docs/app-framework/app-installation/app-permission-authorization.png)

You must click on the `Authorize app` button to proceed. **You can revoke access at any time by deleting the app.**

## 4. Configure your app

Authorizing permissions redirects you to the app configuration screen on your project. 

The last step is filling in the required data in the app configuration screen, if any.

The configuration screen will look different and may require different information depending on the app.

<Alert theme="warning">

**If you're installing an app from our marketplace**, the required information will come from your account in the app you're integrating with, and will be detailed in the integration guide we provide.

**If you're installing a private app that was shared with you**, this information should be provided by the developer.

</Alert>

After you've filled in the required information, save it to finish the process. You'll be able to find the installed app in the **Apps** tab of your project, under **Installed apps**.

## Resources

- [App Framework:](/docs/app-framework) Overview to our **App Framework**, which extends **Hygraph** capabilities, offering the possibility of creating your own custom apps and sharing them with other users.
- [Register an app:](/docs/app-framework/register-an-app) Documentation for developers on how to register an app on the **Hygraph** platform.
- [Using app tokens:](/docs/app-framework/app-tokens) How to exchange a setup code for an app token and use it to authenticate Hygraph API requests.
- [Delete an app:](/docs/app-framework/delete-an-app) Documentation for developers on how to delete an app you have created.
- [First steps:](/docs/app-framework/first-steps/overview) Comprehensive step-by-step guide on how to develop an app with custom field and sidebar elements.
- [Next.js starter:](/docs/app-framework/quick-starters/nextjs) Document that guides you through the process of developing an app with a custom field using our `Next.js` starter.
- [API Reference:](/docs/app-framework/api-reference/api-reference-common) Our App Framework API Reference.


---
# Use app tokens

Source: https://hygraph.com/docs/app-framework/app-tokens

<Alert theme="warning" title="Action required for existing app installations">
  If your app makes API calls using a token injected directly by the App SDK, you need to update it to use the App Token exchange flow described on this page. If your app already uses this flow or does not make API calls, no action is needed.

  Once you've updated and redeployed your app, reinstall it in your project and <Link href="https://hygraph.com/support" target="_blank">notify our team</Link> so we can apply the patch on our end.
</Alert>

App tokens let your app call Hygraph APIs on behalf of the environment it's installed in. You only need to generate an app token if your app accesses the Content API, Management API, or webhooks.

The token is generated during installation by exchanging a setup code for an app token. The setup code is passed as a `code` query parameter and is only available while installation is in progress.

## Prerequisites

Before you start, make sure you have:

- Registered your app and saved the [`Client ID` and `Client Secret` from the **Permissions** tab](/docs/app-framework/register-an-app#permissions).
- Created your app using <Link href="https://nextjs.org/docs/api-reference/create-next-app" target="_blank"><code>create-next-app</code></Link> with the App Router.

## Step 1: Add the token exchange API route

Create `app/api/exchangeSetupCode/route.ts`. This route receives the setup code from your setup page, calls the Hygraph token exchange endpoint with your app credentials, and returns the app token.

<Alert theme="warning">

Store `CLIENT_ID` and `CLIENT_SECRET` as environment variables. Never commit them to your repository.

</Alert>

```ts
import { NextResponse } from "next/server";

type ExchangeSetupCodePayload = {
  code?: string;
  environmentId?: string;
  managementApiBaseUrl?: string;
};

export async function POST(request: Request) {
  let payload: ExchangeSetupCodePayload;

  try {
    payload = (await request.json()) as ExchangeSetupCodePayload;
  } catch {
    return NextResponse.json(
      { message: "Invalid request body. JSON payload is required." },
      { status: 400 },
    );
  }

  const { code, environmentId, managementApiBaseUrl } = payload;

  if (!code || !environmentId || !managementApiBaseUrl) {
    return NextResponse.json(
      {
        message:
          "Missing required fields: code, environmentId, and managementApiBaseUrl are required.",
      },
      { status: 400 },
    );
  }

  if (!process.env.CLIENT_ID || !process.env.CLIENT_SECRET) {
    return NextResponse.json(
      { message: "Server is missing CLIENT_ID or CLIENT_SECRET." },
      { status: 500 },
    );
  }

  try {
    const response = await fetch(`${managementApiBaseUrl}/app-exchange-token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        clientId: process.env.CLIENT_ID,
        clientSecret: process.env.CLIENT_SECRET,
        exchangeCode: code,
      }),
    });

    const data = (await response.json()) as {
      appToken?: string;
      message?: string;
    };

    if (!response.ok) {
      return NextResponse.json(
        {
          message:
            data.message ?? "Failed to exchange setup code for an app token.",
        },
        { status: response.status },
      );
    }

    if (!data.appToken) {
      return NextResponse.json(
        { message: "Hygraph did not return an app token." },
        { status: 502 },
      );
    }

    return NextResponse.json({ appToken: data.appToken });
  } catch {
    return NextResponse.json(
      { message: "Could not reach Hygraph token exchange endpoint." },
      { status: 502 },
    );
  }
}
```

## Step 2: Add the setup page

Create `app/setup/page.tsx`. This page reads the setup code from the URL query parameter, calls your exchange route, and marks the installation as completed.

```ts
"use client";

import { useApp, Wrapper } from "@hygraph/app-sdk-react";
import { useSearchParams } from "next/navigation";
import { useState } from "react";

function Setup({ code }: { code: string }) {
  const { context, updateInstallation } = useApp();
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const managementApiBaseUrl = context.project.mgmtApi
    .split("/")
    .slice(0, -1)
    .join("/");

  const handleConnectApp = async () => {
    setError(null);
    setIsSubmitting(true);

    try {
      if (!code) {
        throw new Error(
          "Missing setup code. Please restart the app installation.",
        );
      }

      const response = await fetch(`/api/exchangeSetupCode`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          code,
          environmentId: context.environment.id,
          managementApiBaseUrl,
        }),
      });

      if (!response.ok) {
        let message = "Failed to connect your app. Please try again.";

        try {
          const errorData = await response.json();
          if (errorData?.message) {
            message = errorData.message;
          }
        } catch {
          // Use default message when response body is not JSON
        }

        throw new Error(message);
      }

      await updateInstallation({ status: "COMPLETED", config: {} });
    } catch (caughtError) {
      setError(
        caughtError instanceof Error
          ? caughtError.message
          : "Something went wrong while connecting your app.",
      );
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <>
      <button onClick={handleConnectApp} disabled={isSubmitting}>
        {isSubmitting ? "Connecting..." : "Connect your app"}
      </button>
      {error ? <p role="alert">{error}</p> : null}
    </>
  );
}

function SetupContent({ code }: { code: string }) {
  const { installation } = useApp();

  if (!installation) {
    return <div>Loading installation...</div>;
  }

  if (installation.status === "COMPLETED") {
    return <div>Installation completed</div>;
  }

  return <Setup code={code} />;
}

export default function SetupPage() {
  const searchParams = useSearchParams();
  const code = searchParams.get("code") ?? "";

  return (
    <Wrapper>
      <SetupContent code={code} />
    </Wrapper>
  );
}
```

## Step 3: Make authenticated API calls

Once installation is complete, retrieve the app token from `context.environment.authToken` and pass it as a `Bearer` token in your API requests.

The example below shows an API route that creates a model using the Management API and a component that calls it.

1. In `app/api/createHygraphModel/route.ts`, create an API route that creates a model using the Management API:

    ```ts
    import { NextResponse } from "next/server";

    const createModelMutation = `
      mutation CreateModelMutation($input: CreateModelInput!) {
        createModel(data: $input) {
          migration {
            id
          }
        }
      }
    `;

    type CreateHygraphModelPayload = {
      appToken?: string;
      environmentId?: string;
      managementApiUrl?: string;
    };

    export async function POST(request: Request) {
      let body: CreateHygraphModelPayload;

      try {
        body = (await request.json()) as CreateHygraphModelPayload;
      } catch {
        return NextResponse.json(
          { message: "Invalid request body. JSON payload is required." },
          { status: 400 },
        );
      }

      if (!body.appToken || !body.environmentId || !body.managementApiUrl) {
        return NextResponse.json(
          {
            message:
              "Missing required fields: appToken, environmentId, and managementApiUrl are required.",
          },
          { status: 400 },
        );
      }

      try {
        const response = await fetch(body.managementApiUrl, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${body.appToken}`,
          },
          body: JSON.stringify({
            query: createModelMutation,
            variables: {
              input: {
                environmentId: body.environmentId,
                apiId: "DemoModel",
                apiIdPlural: "DemoModels",
                displayName: "Demo Model",
                description: "Demo Model Description",
              },
            },
          }),
        });

        const data = (await response.json()) as Record<string, unknown>;

        if (!response.ok) {
          return NextResponse.json(
            { message: "Failed to create Hygraph model.", data },
            { status: response.status },
          );
        }

        return NextResponse.json(data, { status: 200 });
      } catch {
        return NextResponse.json(
          { message: "Could not reach Hygraph management API endpoint." },
          { status: 502 },
        );
      }
    }
    ```

2. In `app/page.tsx`, create a component that calls the route:

    ```ts
    "use client";

    import { Wrapper, useApp } from "@hygraph/app-sdk-react";
    import { useState } from "react";

    function CreateHygraphModel() {
      const { context } = useApp();
      const [isSubmitting, setIsSubmitting] = useState(false);
      const [message, setMessage] = useState<string | null>(null);

      const appToken = context.environment.authToken;

      const handleCreateModel = async () => {
        setMessage(null);
        setIsSubmitting(true);

        const response = await fetch("/api/createHygraphModel", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            appToken,
            environmentId: context.environment.id,
            managementApiUrl: context.project.mgmtApi,
          }),
        });

        const data = (await response.json()) as { message?: string };

        setMessage("🎉 Created Hygraph Model");
        setIsSubmitting(false);
      };

      return (
        <>
          <button onClick={handleCreateModel} disabled={isSubmitting}>
            {isSubmitting ? "Creating..." : "Create Hygraph Model"}
          </button>
          {message ? <p>{message}</p> : null}
        </>
      );
    }

    export default function PageRoute() {
      return (
        <Wrapper>
          <CreateHygraphModel />
        </Wrapper>
      );
    }
    ```

## What's next

- [Register an app](/docs/app-framework/register-an-app): How to configure app permissions and retrieve your Client ID and Client Secret.
- [Install an app](/docs/app-framework/app-installation): How the installation flow works from the user's perspective.
- [First steps](/docs/app-framework/first-steps/overview): Step-by-step tutorial for building an app with field and sidebar elements.
- [API Reference](/docs/app-framework/api-reference/api-reference-common): Full reference for common props, including `context.environment.authToken`.

---
# Constants

Source: https://hygraph.com/docs/app-framework/constants/constants

Constants are predefined, unchanging values that are used throughout the framework to ensure consistency and reliability.

| Name                    | Description                              | Type     | Values                                                                                                                                        |
| ----------------------- | ---------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `ToastVariantColor`     | Possible toast colors                    | `string` | `success`, `error`, `warning`, `info`, `primary`, `dark`, `publish`                                                                           |
| `ToastPosition`         | Position of the toast on the screen      | `string` | `top-right`, `top-center`, `top-left`, `bottom-right`, `bottom-center`, `bottom-left `                                                        |
| `StageColorPalette`     | Color palette for the `stage` interface   | `string` | `PINK`, `PURPLE`, `ORANGE`, `RED`, `BROWN`, `TEAL`, `GREEN`, `YELLOW`                                                                         |
| `UserKind`              | Kind of user                             | `string` | `MEMBER`, `PAT`, `PUBLIC`, `WEBHOOK`                                                                                                          |
| `FieldExtensionType`    | Data type the field is expected to store | `string` | `STRING`, `RICHTEXT`, `INT`, `FLOAT`, `BOOLEAN`, `JSON`, `DATETIME`, `DATE`, `LOCATION`, `COLOR`, `ENUMERATION`, `RELATION`, `ASSET`, `UNION` |
| `FieldExtensionFeature` | How the field should be rendered         | `string` | `FieldRenderer`, `ListRenderer`, `TableRenderer`                                                                                              |
| `AppInstallationStatus` | App installation status                  | `string` | `COMPLETED`, `DISABLED`, `PENDING`                                                                                                            |
| `ColorPalette`          | Possible palette colors                  | `string` | `PINK`, `PURPLE`, `ORANGE`, `RED`, `BROWN`, `TEAL`, `GREEN`, `YELLOW`                                                                         |


---
# How to delete an app you've created

Source: https://hygraph.com/docs/app-framework/delete-an-app

To delete an app, navigate to **Your apps** in the project directory or your user settings, find the card of the app you want to delete, and select the `Delete` option from the context menu.

![Delete app](/images/docs/app-framework/app-framework-delete-fromcard.png)

Since **this is an action that can't be undone and will impact on the projects currently using the app**, you will be asked to confirm your decision to delete it.

![Delete app confirmation](/images/docs/app-framework/app-framework-delete-fromcard-confirmation.png)


---
# openAssetPicker method

Source: https://hygraph.com/docs/app-framework/examples/openassetpicker-method

This document provides an example on how to use the `openAssetPicker` method. It allows you to pick an image from your Hygraph project assets library, and add it to your entry in the content editor. It can be used as an entry field or as part of the sidebar.

Here are the examples of both:

## openAssetPicker as entry field

```ts
function AssetPicker() {
  const { value, onChange, openAssetPicker } = useFieldExtension();

  const onAssetPicker = () => {
    openAssetPicker().then((imageResult) => {
      if (imageResult !== null) {
        onChange(imageResult);
      }
    });
  };

  return (
    <div>
      {value && (
        <Image src={value.url} width={value.width / 3} alt={value.fileName} />
      )}
      <button onClick={onAssetPicker}>Pick Image</button>
    </div>
  );
}
```

This method is mostly used for example purposes. For other uses we have a native [asset picker](/docs/api-reference/schema/field-types#asset) you can use instead.

## openAssetPicker in sidebar

```ts
const { openAssetPicker } = useFormSidebarExtension();
// or
// const { openAssetPicker } = useFieldExtension();

const onAssetPicker = () => {
  openAssetPicker().then((imageResult) => {
    if (imageResult !== null) {
      // do something with the picked asset
      console.log(imageResult);
    }
  });
};
```


---
# Field element declaration

Source: https://hygraph.com/docs/app-framework/field-element/declaration

## Field element properties

| Key           | Type                                                                                                                    | Description                                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `String`                                                                                                                | Name of the field element                                                                                                    |
| `apiId`       | `String`                                                                                                                | API ID of the field element                                                                                                  |
| `type`        | `field` (required)                                                                                                      | The type of element                                                                                                          |
| `features`    | [`[FieldExtensionFeature]`](/docs/app-framework/field-element/declaration#fieldextensionfeature-enumeration) (required) | List of features implemented by the element (at least one)                                                                   |
| `fieldType`   | [`FieldExtensionType`](/docs/app-framework/field-element/declaration#fieldextensiontype-enumeration) (required)         | What field type is your app element targeting                                                                                |
| `url`         | `String`                                                                                                                | URL of the field element                                                                                                     |
| `description` | `String`                                                                                                                | Description of the field element                                                                                             |
| `fieldConfig` | `ConfigFields`                                                                                                          | Optional definition of _field_ configuration settings. Supports the following field types: `string`, `number`, and `boolean` |

## FieldExtensionType enumeration

Supported `FieldExtensionType` enumeration values:

| Type          | `value` type                                                                                                                     |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `STRING`      | `string`. A text field supporting plain strings.                                                                                 |
| `INT`         | `number` (without decimals). A numeric field for whole numbers (integers).                                                       |
| `FLOAT`       | `number`. A numeric field that supports decimal values.                                                                          |
| `BOOLEAN`     | `boolean`. A true/false field type.                                                                                              |
| `JSON`        | Any valid <Link href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON" target="_blank">JSON</Link> value                    |
| `DATE`        | `string` in format 'yyyy-MM-dd'                                                                                                  |
| `DATETIME`    | `string` in <Link href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString" target="_blank">ISO 8601 format</Link> |
| `LOCATION`    | A field for geographic coordinates (latitude/longitude). `object { "latitude": number; "longitude": number; }`                   |
| `COLOR`       | An RGBA color value. `object { "rgba": { "r": number; "g": number; "b": number; "a": number; } }`                                |
| `RICHTEXT`    | `object`. Formatted text, embedded media, and links.                                                                             |
| `ENUMERATION` | `string`. A predefined set of selectable values (e.g., dropdown options).                                                        |
| `ID`          | `string`. A unique identifier for fields or entries, typically system-generated.                                                 |
| `RELATION`    | `object`. A field that defines a relationship between different models or entries.                                               |
| `UNION`       | `object`. A type of reference field that allows referencing multiple models.                                                     |

## FieldExtensionFeature enumeration

- `FieldRenderer`: The element replaces a form field.
- [`ListRenderer`](/docs/app-framework/field-element/list-renderer): By enabling this feature, you indicate
  that the element can handle array values as well, and that Hygraph should call
  it directly instead of the default list renderer on multiple value inputs.
- [`TableRenderer`](/docs/app-framework/field-element/table-renderer): The element should also be used to display values in the content table.

## Field configuration

This is an example for the `JSON` object for the field configuration:

```json
{
  "CUSTOM_COLORS": {
    "type": "string",
    "description": "Enter color options to display, separated by comma. E.g.: #fff, #f00, #0f0",
    "displayName": "Colors"
  }
}
```

According to this example, when the form is rendered, it will render a field called `CUSTOM_COLORS` of type `string`, with the display name **"Colors"**, and the description **"Enter color options to display, separated by a comma. E.g.: #fff, #f00, #0f0"**.

This information will be sent as metadata to the app element, and will display in the schema editor - as part of the custom field that it was configured for - and users will be able to add it to their models.

The schema view of the above example would look like this:

![fieldConfig example - Field](/images/docs/app-framework/app-framework-fieldConfig-field.png)

To later retrieve this information, you can do this:

```js
// Reading config data in Field Extension
function FieldElement() {
  const {
    extension: { fieldConfig },
  } = useFieldExtension();
  const colorsConfig = fieldConfig?.colors;

  return <div>{colorsConfig}</div>;
}
```


---
# List renderer

Source: https://hygraph.com/docs/app-framework/field-element/list-renderer

Like default Hygraph fields, the fields in an app can be configured to store multiple values.

To enable custom list rendering in your app, add `ListRenderer` to the `features` field in the [Elements](/docs/app-framework/register-an-app#elements) tab of the [app registration](/docs/app-framework/register-an-app) process.

![ListRenderer](/images/docs/app-framework/app-framework-listrenderer.png)

Your extension will now need to be able to handle an array of values. A simple example of adding a new value would be to spread the array that you get back from the API and add your new value to it.

To check whether the current extension instance is a multiple-value field, use the `field.isList` boolean:

<Tabs panelHeight={470}>
  <TabsItem label="Native JS">

```js
init({
  declaration,
}).then((initialState) => {
  const { status, props } = initialState;
  if (status === 'ok') {
    const {
      value,
      onChange,
      field: { isList },
    } = props;
    const insertHandler = (newValue) => {
      if (isList) {
        onChange([...value, newValue]);
      } else {
        onChange(newValue);
      }
    };
  }
});
```

</TabsItem>
<TabsItem label="React">

```js
const {
  value,
  onChange,
  field: { isList },
} = useFieldExtension();

const insertHandler = (newValue) => {
  if (isList) {
    onChange([...value, newValue]);
  } else {
    onChange(newValue);
  }
};
```

</TabsItem>
</Tabs>


---
# Table renderer

Source: https://hygraph.com/docs/app-framework/field-element/table-renderer

You can define how custom field values are displayed in the content table.

To enable custom table-cell rendering in your app, add `TableRenderer` to the `features` field in the [Elements](/docs/app-framework/register-an-app#elements) tab of the [app registration](/docs/app-framework/register-an-app) process.

![TableRenderer](/images/docs/app-framework/app-framework-tablerenderer.png)

The SDK provides a `isTableCell` boolean that you can use to detect that the current extension instance is rendered in the content table:

How you handle table-cell rendering is up to you. Hygraph will only enforce a cell height of 60px in order to preserve other fields' functionality in the table layout.

Let's emulate a simple string field preview that conditionally displays the value in a paragraph:

<Tabs>
<TabsItem label="React">

```js
import {
  Wrapper,
  useFieldExtension,
} from '@hygraph/app-sdk-react';

const CustomStringInput = () => {
  const { value, onChange, isTableCell } = useFieldExtension();
  if (isTableCell) {
    return <p>{value}</p>;
  }
  return (
    <input
      value={value}
      onChange={({ target: { value: val } }) => onChange(val)}
    />
  );
};

const Extension = () => {
  return (
    <Wrapper>
      <CustomStringInput />
    </Wrapper>
  );
};
```

</TabsItem>
</Tabs>

## Multiple values

What happens if your extension supports lists? By combining the two features, `TableRenderer` and [`ListRenderer`](/docs/app-framework/field-element/list-renderer), you can determine how multiple-value fields should behave in content table.

Let us augment the previous example to account for list values:

```js
import { Wrapper, useFieldExtension } from '@hygraph/app-sdk-react';

const CustomStringInput = () => {
  const {
    value,
    onChange,
    isTableCell,
    field: { isList },
  } = useFieldExtension();
  if (isTableCell) {
    if (isList) {
      return (
        <div>
          {value.map((item) => (
            <p>{item}</p>
          ))}
        </div>
      );
    }
    return <p>{value}</p>;
  }
  if (isList) {
    return (
      <input
        value={value}
        onChange={({ target: { value: val } }) => onChange([...value, val])}
      />
    );
  }
  return (
    <input
      value={value}
      onChange={({ target: { value: val } }) => onChange(val)}
    />
  );
};

const Extension = () => {
  return (
    <Wrapper>
      <CustomStringInput />
    </Wrapper>
  );
};
```

## Preview expansion

The example above would work for simple cases, but you'll likely need more space than a table cell allows.

For those cases, the SDK provides you with tools to display the content of a custom field in full-screen mode.

Extract the `expand` handler that takes a boolean as an argument and `isExpanded` prop by calling the `useFieldExtension` hook:

```js
const { isTableCell, expand, isExpanded } = useFieldExtension();
```

Instead of displaying the value directly in the table cell, you can now render a button that would expand the preview. A basic example would be something like this:

```js
if (isTableCell) {
  if (isExpanded) {
    return (
      <div>
        <p>{value}</p>
        <button onClick={() => expand(false)}>Close</button>
      <div>
    );
  } else {
    return (
      <button onClick={() => expand(true)}>
        Preview
      </button>
    );
  }
}
```


---
# Develop your app configuration flow

Source: https://hygraph.com/docs/app-framework/first-steps/develop-configuration-flow

This demo app's configuration flow will involve a mock login process that creates an `accessToken`, stores it in `localStorage`, sets an app's status as `COMPLETED`, and stores a config value.

<Alert theme="warning">

Using `localStorage` is an unsafe way to store access tokens. Please note that we're only using it here as an example.

</Alert>

```tsx
import React from 'react';
import { useApp, Wrapper } from '@hygraph/app-sdk-react';

function Install() {
  const { accessToken, login } = useLogin();
  const { updateInstallation, installation } = useApp();
  if (accessToken) {
    return <div>Connected as name@example.com</div>;
  }
  if (installation.status === 'COMPLETED') {
    return <div>App installation successful</div>;
  }
  return (
    <button
      onClick={async () => {
        login();
        await updateInstallation({
          status: 'COMPLETED',
          config: { KEY: 'value' },
        });
      }}
    >
      Connect to app
    </button>
  );
}

function useLogin() {
  const [accessToken, setAccessToken] = React.useState<string>('');
  function login() {
    setAccessToken('123456');
    localStorage.setItem('appToken', accessToken);
  }
  return { accessToken, login };
}

export default function Page() {
  return (
    <Wrapper>
      <Install />
    </Wrapper>
  );
}
```

<Alert title="Choose your journey" theme="success">

**Are you building a custom field element?** Click [here](/docs/app-framework/first-steps/develop-field-element) to continue.

**Are you building a sidebar element?** Click [here](/docs/app-framework/first-steps/develop-sidebar-element) to continue.

**Are you building a page element?** Click [here](/docs/app-framework/first-steps/develop-page-element) to continue.

</Alert>


---
# Develop your app's field elements

Source: https://hygraph.com/docs/app-framework/first-steps/develop-field-element

To **create the element**, create a file inside `pages` and name it `custom-field.tsx` with the following content:

```jsx
import { Wrapper } from '@hygraph/app-sdk-react';

export default function CustomField() {
  return (
    <Wrapper>
      <label for="custom_field">Custom Field:</label>
      <input id="custom_field" placeholder="Type something here" type="text" />
    </Wrapper>
  );
}
```

In this example, you are naming the file `custom-field.tsx` because at the time of [registering the app](/docs/app-framework/first-steps/register-your-app#field-element) you used `http://localhost:3000/custom-field` as your `URL`.

<Alert theme="warning">

Please note that **Wrapper** should be the parent of your component whenever you use the `useFieldExtension` hook.

</Alert>

**Adding React SDK**

Let's import some SDK components, hooks and enumerations from Hygraph SDK.

Start with importing `useFieldExtension` hook from the library inside your React application.

You should add the following code at the top of the `custom-field.tsx` file, under the wrapper. Remember to import `useEffect` hook at the top.

```jsx
// Add this at the top of your custom-field.tsx file

import { useState, useEffect } from 'react';

import { Wrapper, useFieldExtension } from '@hygraph/app-sdk-react';
```

Then, add `useFieldExtension` hook into `MyField` and adjust the code accordingly, like the following example:

```jsx
function MyCustomField() {
  const { value, onChange } = useFieldExtension();
  const [localValue, setLocalValue] = useState(value || '');

  useEffect(() => {
    onChange(localValue);
  }, [localValue, onChange]);

  return (
    <>
      <label for="custom_field">Custom Field:</label>
      <input
        id="custom_field"
        value={localValue}
        onChange={(e) => setLocalValue(e.target.value)}
      />
    </>
  );
}
```

Finally, let's wrap our custom input field with the `Wrapper` component:

```jsx
export default function CustomField() {
  return (
    <Wrapper>
      <MyCustomField />
    </Wrapper>
  );
}
```

Your complete custom app element should look like this:

```jsx
// this is the complete code

import { useState, useEffect } from 'react';

import { Wrapper, useFieldExtension } from '@hygraph/app-sdk-react';

function MyCustomField() {
  const { value, onChange } = useFieldExtension();
  const [localValue, setLocalValue] = useState(value || '');

  useEffect(() => {
    onChange(localValue);
  }, [localValue, onChange]);

  return (
    <>
      <label for="custom_field">Custom Field:</label>
      <input
        id="custom_field"
        value={localValue}
        onChange={(e) => setLocalValue(e.target.value)}
      />
    </>
  );
}
export default function CustomField() {
  return (
    <Wrapper>
      <MyCustomField />
    </Wrapper>
  );
}
```

<Alert title="Next steps" theme="success">

Congratulations! Now that you've registered and developed your app, you are ready to [install it](/docs/app-framework/app-installation) and try it out, if you didn't install it already while testing it!

You may also want to access more in depth information about the app registration process, along with all the options available as well as all possible actions you can take in the registration form. [Click here](/docs/app-framework/register-an-app) to know more.

If you have any questions, you're welcome to <Link href="https://hygraph-community.slack.com/" target="_blank">join our community!</Link>

</Alert>


---
# Develop your app installation flow

Source: https://hygraph.com/docs/app-framework/first-steps/develop-installation-flow

Setup pages handle both installation and configuration once users have already installed the app.

You can use `useApp().updateInstallation` to set the app's `status` to `PENDING`, `COMPLETED` or `DISABLED`. You can also use it to store `config` values.

If your app calls the Hygraph Content API, Management API, or webhooks, you need to exchange a setup code for an app token before calling `updateInstallation`. See [Use app tokens](/docs/app-framework/app-tokens) for the full exchange flow.

A simple install flow would be setting the app as `COMPLETED`, this will create an app installation for the users that go through this flow. It's in a `PENDING` state, but already installed. This is what that flow would look like in code:

```jsx
import React from 'react';
import { useApp, Wrapper } from '@hygraph/app-sdk-react';

function Setup() {
  const { installation } = useApp();
  if (installation.status === 'COMPLETED') {
    return <Configure />;
  }
  return <Install />;
}

function Install() {
  const { updateInstallation } = useApp();

  return (
    <button
      onClick={() => {
        updateInstallation({ status: 'COMPLETED', config: {} });
      }}
    >
      Install App
    </button>
  );
}

function Configure() {
  return <div>Configure</div>;
}

export default function Page() {
  return (
    <Wrapper>
      <Setup />
    </Wrapper>
  );
}
```

<Alert theme="success">

The next step is to **develop your app's configuration flow**, click [here](/docs/app-framework/first-steps/develop-configuration-flow) to continue.

</Alert>

---
# Develop your app page elements

Source: https://hygraph.com/docs/app-framework/first-steps/develop-page-element

To **create the element**, create a file inside `pages` and name it `page.tsx` with the following content:

```jsx
import { Wrapper } from '@hygraph/app-sdk-react';

export default function Page() {
  return (
    <Wrapper>
      <h1>Hello, Hygraphers!</h1>
      <p>Here is the description</p>
    </Wrapper>
  );
}
```

In this example, you are naming the file `page.tsx` because at the time of [registering the app](/docs/app-framework/first-steps/register-your-app#page-element) you used `http://localhost:3000/page` as your `URL`.

<Alert theme="warning">

Please note that **Wrapper** should be the parent of your component whenever you use the `useApp` hook.

</Alert>

Next, import `useApp()` at the top, then create `PageElement` component and move code there.

Then you need to get the installation object from `useApp()` to display you app name, description, and icon.

```jsx
import { Wrapper, useApp } from '@hygraph/app-sdk-react';

function PageElement() {
  const { installation } = useApp();
  return (
    <div>
      <div>
        {/* <!-- This is the app avatar --> */}
        <img src={installation.app.avatarUrl} width="32" height="32" />
      </div>

      {/* <!-- This is the app name --> */}
      <h1>{installation.app.name}</h1>

      {/* <!-- This is the app description --> */}
      <p>{installation.app.description}</p>
    </div>
  );
}

export default function Page() {
  return (
    <Wrapper>
      <PageElement />
    </Wrapper>
  );
}
```

Then, add `showToast`:

```jsx
import { Wrapper, useApp } from '@hygraph/app-sdk-react';

function PageElement() {
  const { installation, showToast } = useApp();
}
```

After that, add button with `handleClick` method:

```jsx
return (
  <div>
    <div>
      {/* <!-- This is the app avatar --> */}
      <img src={installation.app.avatarUrl} width="32" height="32" />
    </div>

    {/* <!-- This is the app name --> */}
    <h1>{installation.app.name}</h1>

    {/* <!-- This is the app description --> */}
    <p>{installation.app.description}</p>

    {/* <!-- Add button --> */}
    <div>
      <button onClick={handleClick}>Click Me!</button>
    </div>
  </div>
);
```

And finally, add `handleClick` method, triggering `showToast`:

```jsx
function PageElement() {
  const { installation, showToast } = useApp();

  const handleClick = () => {
    showToast({
      title: 'Hello World!',
      description: 'This is a toast message',
      variantColor: 'success',
    });
  };

  // rest of code
}
```

Your complete custom app element should look like this:

```jsx
// this is the complete code

import { Wrapper, useApp } from '@hygraph/app-sdk-react';

function PageElement() {
  const { installation, showToast } = useApp();

  const handleClick = () => {
    showToast({
      title: 'Hello World!',
      description: 'This is a toast message',
      variantColor: 'success',
    });
  };

  return (
    <div>
      <div>
        {/* <!-- This is the app avatar --> */}
        <img src={installation.app.avatarUrl} width="32" height="32" />
      </div>

      {/* <!-- This is the app name --> */}
      <h1>{installation.app.name}</h1>

      {/* <!-- This is the app description --> */}
      <p>{installation.app.description}</p>

      {/* <!-- Add button --> */}
      <div>
        <button onClick={handleClick}>Click Me!</button>
      </div>
    </div>
  );
}

export default function Page() {
  return (
    <Wrapper>
      <PageElement />
    </Wrapper>
  );
}
```

<Alert title="Next steps" theme="success">

Congratulations! Now that you've registered and developed your app, you are ready to [install it](/docs/app-framework/app-installation) and try it out, if you didn't install it already while testing it!

You may also want to access more in depth information about the app registration process, along with all the options available as well as all possible actions you can take in the registration form. [Click here](/docs/app-framework/register-an-app) to know more.

If you have any questions, you're welcome to <Link href="https://hygraph-community.slack.com/" target="_blank">join our community!</Link>

</Alert>


---
# Develop your app's sidebar elements

Source: https://hygraph.com/docs/app-framework/first-steps/develop-sidebar-element

To **create the element**, create a file inside `pages` and name it `google-serp-preview.tsx` with the following content:

```jsx
import { Wrapper } from '@hygraph/app-sdk-react';

export default function GoogleSerpPreview() {
  return <Wrapper>// here goes your custom sidebar code</Wrapper>;
}
```

In this example, you are naming the file `google-serp-preview.tsx` because at the time of [registering the app](/docs/app-framework/first-steps/register-your-app#sidebar-element) you used `http://localhost:3000/google-serp-preview` as your `URL`.

<Alert theme="warning">

Please note that **Wrapper** should be the parent of your component whenever you use the `useFormSidebarExtension` hook.

</Alert>

**Adding React SDK**

Now, let's import some SDK components and hooks from Hygraph SDK.

Start with importing the `Wrapper` component and `useFormSidebarExtension` hook from the library inside your React application.

You should add the following code at the top of the `google-serp-preview.tsx` file.

```jsx
// Add this at the top of your google-serp-preview.tsx file

import { Wrapper, useFormSidebarExtension } from '@hygraph/app-sdk-react';
```

Then, add `useFormSidebarExtension` hook into `SerpPreview` and adjust the code accordingly, like the following example:

```jsx
import { Wrapper, useFormSidebarExtension } from '@hygraph/app-sdk-react';

const SerpPreview = () => {
  const { extension } = useFormSidebarExtension();

  return (
    <>
      <h3>{extension.name}</h3>
      <div>{extension.description}</div>
    </>
  );
};
```

Finally, let's wrap our custom input field with the `Wrapper` component. Remember to pass in declaration:

```jsx
const GoogleSerpPreview = () => {
  return (
    <Wrapper>
      <SerpPreview />
    </Wrapper>
  );
};

export default GoogleSerpPreview;
```

Your complete custom sidebar code should look like this:

```jsx
// this is the complete code

import { Wrapper, useFormSidebarExtension } from '@hygraph/app-sdk-react';

const SerpPreview = () => {
  const { extension } = useFormSidebarExtension();

  return (
    <>
      <h3>{extension.name}</h3>
      <div>{extension.description}</div>
    </>
  );
};

const GoogleSerpPreview = () => {
  return (
    <Wrapper>
      <SerpPreview />
    </Wrapper>
  );
};

export default GoogleSerpPreview;
```

Finally, you should import your custom React component to `App.js`.

```js
// App.js

import GoogleSerpPreview from './extensions/GoogleSerpPreview';

function App() {
  return (
    <div className="App">
      <GoogleSerpPreview />
    </div>
  );
}

export default App;
```

<Alert title="Next steps" theme="success">

Congratulations! Now that you've registered and developed your app, you are ready to [install it](/docs/app-framework/app-installation) and try it out, if you didn't install it already while testing it!

You may also want to access more in depth information about the app registration process, along with all the options available as well as all possible actions you can take in the registration form. [Click here](/docs/app-framework/register-an-app) to know more.

If you have any questions, you're welcome to <Link href="https://hygraph-community.slack.com/" target="_blank">join our community!</Link>

</Alert>


---
# Develop your application

Source: https://hygraph.com/docs/app-framework/first-steps/develop-your-application

You will now bootstrap your development environment, create a basic setup page and test it inside a Hygraph project.

## 1. Bootstrap your development environment

Run the following command on your terminal to create a Next.js application:

```
npx create-next-app@latest --ts
```

Go to the generated folder and start it by running this command:

```
yarn dev
```

You can see your application by navigating to `http://localhost:3000`.

Install the Hygraph React App SDK with the following command:

```
yarn add @hygraph/app-sdk-react
```

## 2. Create a basic setup page

Create a setup page at `pages/setup.tsx`, since the file name needs to match the **Setup URL** you defined while registering the app in Hygraph.

This is what the setup page should look like, it's just placeholder text for now:

```jsx
import { Wrapper } from '@hygraph/app-sdk-react';

export default function Setup() {
  return <Wrapper>Hello Hygraph</Wrapper>;
}
```

<Alert theme="warning">

Navigating to `http://localhost:3000/setup` doesn't show `Hello Hygraph`, but shows `SDK connection error, check logs` instead. This is because apps need to be connected to Hygraph to work.

</Alert>

## 3. Test your app inside a Hygraph project

Go to a Hygraph project where you will test the app you created. Go to `https://app.hygraph.com/:projectId/:environmentId/apps/:appApiId:/new`. Replace `projectId` and `environmentId` with their values from your project's URL.

You should now see `Hello Hygraph`. The next step is implementing a setup installation flow instead.

You can also navigate to the user menu of your Hygraph project, select `Your apps`, and install the App from there:

![Install apps](/images/docs/app-framework/app-framework-install-app.png)

<Alert theme="warning">

The UI will present you with the permissions screen, which you need to authorize to continue testing your app.

</Alert>

<Alert theme="success">

The next step is to develop your app installation flow. [Click here](/docs/app-framework/first-steps/develop-installation-flow) to continue.

</Alert>


---
# App Framework first steps

Source: https://hygraph.com/docs/app-framework/first-steps/overview

## Overview

This is our App Framework tutorial, where you will learn how to create apps using the <Link href="https://www.npmjs.com/package/@hygraph/app-sdk-react" target="_blank">Hygraph App SDK</Link>.

Going through this process, you will have the option to create an example app that will add a custom field to your content entries, or a new widget for content editors, which appears on their form sidebar.

<Alert theme="warning">

Please note that this process allows you to create apps that need to be run inside the platform, and will therefore not work outside of Hygraph.

This tutorial provides data to fill in the basic information relevant to this example. When you create your own application, you will need to replace this with your own information.

</Alert>

## What you will build

In this section you will have the option to follow two paths:

- Creating an app with a custom field using the Hygraph App SDK. It's a basic input field to store text data.
- Creating an app with a **Google SERP Preview** Sidebar element. It will display a preview of how your content would appear on Google Search Results.

## Prerequisites

**Setup**

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) to test the app in.
- You need the latest LTS version of Node.js installed on your machine. If you don't have it, you can <Link href="https://nodejs.org/en/download/" target="_blank">download it here</Link>

**Knowledge**

- Be familiar with the Hygraph platform. If you're not yet familiar with Hygraph, [check out our quickstart](/docs/getting-started/fundamentals/quickstart#create-a-project).
- Be familiar with JavaScript
- Be familiar with React
- Be familiar with Next.js

<Alert theme="success">

**Let's get started!** The first step is to **register your app**, click [here](/docs/app-framework/first-steps/register-your-app) to continue.

</Alert>


---
# Register your app

Source: https://hygraph.com/docs/app-framework/first-steps/register-your-app

## Overview

When you decide to build an app for Hygraph, you must register it on the platform.

In this tutorial, we are only going to complete the basic information in the [General](/docs/app-framework/register-an-app#general), [Permissions](/docs/app-framework/register-an-app#permissions) and [Elements](/docs/app-framework/register-an-app#elements) tabs.

If you want in depth information about the app registration process, along with all the options available, as well as all possible actions you can take in the registration form, [click here](/docs/app-framework/register-an-app).

**Let's get started:**

Navigate to **Your apps** in the project directory or your user settings, then click on the `+ Add new app` button. This will lead you to the <Link href="https://app.hygraph.com/apps/new" target="_blank">App registration form</Link>.

![Your apps](/images/docs/app-framework/app-framework-addnewapp.png)

## General

In the **General** tab of the app registration process, fill in the following information:

![App registration - General](/images/docs/app-framework/app-framework-register-general.png)

- **Name:** This is the name of your app. For this example, write `App SDK Demo`.
- **Description:** A description for what your app does. For this example, write `Example App Framework Application`.
- **Avatar URL:** URL that indicates where your logo is hosted. For this example, use `https://i.pravatar.cc/300?img=69`.
- **API ID:** Write your API ID here. The ID is globally unique, so the form will let you know if the name is taken. This field only allows alphanumeric characters, underscores and hyphens, and you must start with a lowercase letter. This field becomes read-only once the app is created.
- **Setup URL:** The setup URL is the form that displays when you install an app for the first time in Hygraph. For this example, write `http://localhost:3000/setup`.

## Permissions

This section shows the access details of your app.

![App registration - Permissions](/images/docs/app-framework/app-framework-register-permissions.png)

For this tutorial, we suggest you give read/write permissions but you can select your own.

[Check out this document to check what each permission does.](/docs/app-framework/register-an-app#permissions)

<Alert theme="warning">

Permissions can't be edited after the initial save. Consider this information when creating your own app outside of this tutorial.

</Alert>

## Elements

![App registration - elements](/images/docs/app-framework/app-framework-register-elements.png)

<Alert title="What are you building?" theme="info">

**Are you building a custom field element?** Click [here](/docs/app-framework/first-steps/register-your-app#field-element) to continue.

**Are you building a sidebar element?** Click [here](/docs/app-framework/first-steps/register-your-app#sidebar-element) to continue.

**Are you building a page element?** Click [here](/docs/app-framework/first-steps/register-your-app#page-element) to continue.

</Alert>

### Field element

- **Elements:** Add an element by clicking on `+ Add element`:
  - **Name:** Name of your element. For this example, write `Custom field`.
  - **API ID:** Your element's API ID. For this example, write `appCustomField`.
  - **Type:** This is the element type. For this example, select `field` from the dropdown menu.
  - **URL:** The element's dedicated URL. For this example, write `http://localhost:3000/custom-field`.
  - **Description:** It's the description that will appear under your field name in the Schema. For this example, write `Custom field`.

After you've filled in all the information provided for this example, you can save your app by clicking on the `Register app` button.

The next step is to develop your application. [Click here](/docs/app-framework/first-steps/develop-your-application) to continue.

### Sidebar element

- **Elements:** Add an element by clicking on `+ Add element`:
  - **Name:** Name of your element. For this example, write `Google SERP Preview`.
  - **API ID:** Your element's API ID. For this example, write `appFormSidebar`.
  - **Type:** This is the element type. For this example, select `formSidebar` from the dropdown menu.
  - **URL:** The element's dedicated URL. For this example, write `http://localhost:3000/google-serp-preview`.
  - **Description:** It's the description that will appear under your field name in the Schema. For this example, write `Google SERP Preview`.

After you've filled in all the information provided for this example, you can save your app by clicking on the `Register app` button.

<Alert theme="success">

The next step is to develop your application. [Click here](/docs/app-framework/first-steps/develop-your-application) to continue.

</Alert>

### Page element

- **Elements:** Add an element by clicking on `+ Add element`:
  - **Name:** Name of your element. For this example, write `Custom page view`.
  - **API ID:** Your element's API ID. For this example, write `custom-page-view`.
  - **Type:** This is the element type. For this example, select `page` from the dropdown menu.
  - **URL:** The element's dedicated URL. For this example, write `http://localhost:3000/page`.
  - **Description:** It's the description that will appear under your field name in the Schema. For this example, write `Custom page view`.

After you've filled in all the information provided for this example, you can save your app by clicking on the `Register app` button.

<Alert theme="success">

The next step is to develop your application. [Click here](/docs/app-framework/first-steps/develop-your-application) to continue.

</Alert>

## Resources

- [App Framework:](/docs/app-framework) Overview to our **App Framework**, which extends **Hygraph** capabilities, offering the possibility of creating your own custom apps and sharing them with other users.
- [Register an app:](/docs/app-framework/register-an-app) Documentation for developers on how to register an app on the **Hygraph** platform.
- [Using app tokens:](/docs/app-framework/app-tokens) How to exchange a setup code for an app token and use it to authenticate Hygraph API requests.
- [Install an app:](/docs/app-framework/app-installation) Step by step guide on how to install an app in your **Hygraph** project.
- [Delete an app:](/docs/app-framework/delete-an-app) Documentation for developers on how to delete an app you have created.
- [Next.js starter:](/docs/app-framework/quick-starters/nextjs) Document that guides you through the process of developing an app with a custom field using our `Next.js` starter.
- [API Reference:](/docs/app-framework/api-reference/api-reference-common) Our App Framework API Reference.


---
# OpenDialog

Source: https://hygraph.com/docs/app-framework/functions/opendialog

**OpenDialog**(src, props)<br></br>
Opens a separate dialog where you can load data from an external source or create your own UI.

**Parameters**

- `src`<br></br>
  **type** *`string`*<br></br>
  The URL where the dialog contents are located.<br></br>

- `props`
  - `disableOverlayClick`<br></br>
    **type** *`boolean`*<br></br>
    State of the overlay click<br></br>
    If true, the dialog doesn't close when clicking outside of the dialog area
  - `maxWidth`<br></br>
    **type** *`string`*<br></br>
    The maximum width of the dialog
  - `ariaLabel`<br></br>
    **type** *`string`*<br></br>
    Accessibility. `ariaLabel` can be used in cases where text that could label the element is not visible

**Returns**

`Promise<DialogReturn | null>`

&nbsp;

&nbsp;


---
# ShowToast

Source: https://hygraph.com/docs/app-framework/functions/showtoast

**ShowToast**(options)<br></br>
Shows toast notifications on the screen.

**Parameters**

- `options`<br></br>
  **type** *`object`*<br></br>
  [`ToastOptions`](/docs/app-framework/functions/toastoptions) object

**Returns**

`Promise<Id | number, string>`

&nbsp;

&nbsp;


---
# ToastOptions

Source: https://hygraph.com/docs/app-framework/functions/toastoptions

**ToastOptions**(title, description, variantColor, id, isClosable, position, duration)<br></br>
Determines format of the toast.

**Parameters**

- `title`<br></br>
  **type** *`string`*<br></br>
  Toast title

- `description`<br></br>
  **type** *`string`*<br></br>
  Toast description

- `variantColor`<br></br>
  **type** *`string`*<br></br>
  Color of the toast<br></br>
  Key of [`ToastVariantColor`](/docs/app-framework/constants/constants)

- `id`<br></br>
  **type** *`string` | `number`*<br></br>
  Toast Id

- `isClosable`<br></br>
  **type** *`boolean`*<br></br>
  If true, the toast can be closed

- `position`<br></br>
  **type** *`string`*<br></br>
  Position of the toast on the screen<br></br>
  Key of [`ToastPosition`](/docs/app-framework/constants/constants)

- `duration`<br></br>
  **type** *`number`*<br></br>
  Duration of the toast on the screen

&nbsp;

&nbsp;


---
# useApp

Source: https://hygraph.com/docs/app-framework/functions/useapp

**useApp**()<br></br>
Hook function for page elements.

**Properties**

- `installation`<br></br>
  **type** _`object`_<br></br>
  An object with an id, installation status, and config object
  - `id`<br></br>
    **type** _`string`_<br></br>
    Id of the current installation
  - `config`<br></br>
    **type** _`any`_<br></br>
    Object used to store installation relevant config information
  - `status`<br></br>
    **type** _`string`_<br></br>
    Key of [`AppInstallationStatus`](/docs/app-framework/constants/constants)<br></br>
- `context`<br></br>
  **type** _`object`_<br></br>
  Contextual information.<br></br>
  An object with project and environment properties<br></br>
  Environment context, including `authToken`, `endpoint`, `id`, and `name`. `authToken` contains the app token for the current environment and is available after installation status is set to COMPLETED.<br></br>
- `historyPush`<br></br>
  **type** _`function`_<br></br>
  Function to redirect inside Hygraph (internal - path included)<br></br>
- `historyReplace`<br></br>
  **type** _`function`_<br></br>
  Function to replace the current entry on the history stack inside Hygraph (internal - path included)<br></br>
- `openAssetPicker`<br></br>
  **type** _`function`_<br></br>
  Function to open the Hygraph asset picker<br></br>
  See the Asset type in your Content API<br></br>
  [openAssetPicker example](/docs/app-framework/examples/openassetpicker-method)<br></br>
- `openDialog`<br></br>
  **type** _`function`_<br></br>
  Opens a separate dialog where you can load data from an external source or create your own UI<br></br>
  [openDialog documentation](/docs/app-framework/functions/opendialog)<br></br>
- `redirectParent`<br></br>
  **type** _`function`_<br></br>
  Function to make a full redirect (external - hostname + path included)<br></br>
- `showToast`<br></br>
  **type** _`function`_<br></br>
  Function to show Hygraph native toast<br></br>
  [showToast documentation](/docs/app-framework/functions/showtoast)<br></br>
- `updateInstallation`<br></br>
  **type** _`function`_<br></br>
  Function to get the current app installation status, and update it<br></br>
  This function is only available inside the `setup` page<br></br>
  Setting status to COMPLETED makes context.environment.authToken available for authenticating API requests<br></br>
  Installation status is a key of [`AppInstallationStatus`](/docs/app-framework/constants/constants)<br></br>

**Returns**

`<AppProps>`<br></br>
`AppProps` are [common props](/docs/app-framework/api-reference/api-reference-common) + `installation`

&nbsp;

&nbsp;


---
# useFieldExtension

Source: https://hygraph.com/docs/app-framework/functions/usefieldextension

**useFieldExtension**()<br></br>
Hook function for field elements.

**Properties**

- `name`<br></br>
  **type** *`string`*<br></br>
  Name of the field in the form.<br></br>
- `locale`<br></br>
  **type** *`string`*<br></br>
  Current locale on localized field.<br></br>
- `entryId`<br></br>
  **type** *`string` | `null`*<br></br>
  Id of the current entry, null on a new entry.<br></br>
- `isTableCell`<br></br>
  **type** *`boolean`*<br></br>
  Whether or not the field displays in a table view.<br></br>
- `value`<br></br>
  **type** *`any`*<br></br>
  Value field.<br></br>
- `onBlur`<br></br>
  **type** *`method`*<br></br>
  Is triggered when an HTML element loses focus.<br></br>
- `onChange`<br></br>
  **type** *`method`*<br></br>
  Is triggered when you change the value.<br></br>
- `onFocus`<br></br>
  **type** *`method`*<br></br>
  Is triggered when an element gets focus.<br></br>
- `meta`<br></br>
  - `active`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not the field currently has focus.<br></br>
  - `error`<br></br>
    **type** *`any`*<br></br>
    The current validation error for the field.<br></br>
  - `touched`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not this field has ever gained and lost focus.<br></br>
    It can be useful to indicate when to display error messages.<br></br>
- `form`<br></br>
  **type** *`Object` | `Form`*<br></br>
  Contains methods to interact with the content form<br></br>
- `field`<br></br>
  - `id`<br></br>
    **type** *`string`*<br></br>
    Id of the current field.<br></br>
  - `apiId`<br></br>
    **type** *`string`*<br></br>
    apiId of the current field.<br></br>
  - `description`<br></br>
    **type** *`string` | `null`*<br></br>
    Description of the current field.<br></br>
  - `displayName`<br></br>
    **type** *`string` | `null`*<br></br>
    Display name of the current field.<br></br>
  - `isList`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not not the current field is a list.<br></br>
  - `isLocalized`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not the current field is localized.<br></br>
  - `isRequired`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not the current field is required.<br></br>
  - `isUnique`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not the current field is unique.<br></br>
  - `isUnique`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not the current field is unique.<br></br>
  - `isPreview`<br></br>
    **type** *`boolean`*<br></br>
    Whether or not the current field is a preview. True when in version or stage comparison view<br></br>
  - `type`<br></br>
    **type** *`FieldExtensionType`*<br></br>
    Key of [`FieldExtensionType`](/docs/app-framework/constants/constants).<br></br>
- `model`<br></br>
  **type** *`Model`*<br></br>
  Details about the current model.<br></br>
- `extension`<br></br>
  - `config`<br></br>
    **type** *`object`*<br></br>
    Global configuration of the field.<br></br>
  - `fieldConfig`<br></br>
    **type** *`object`*<br></br>
    Configurations that display at the field level.<br></br>
  - `tableConfig`<br></br>
    **type** *`object`*<br></br>
    Configurations that display at the table level.<br></br>
- `isExpanded`<br></br>
  **type** *`boolean`*<br></br>
  Whether or not the field is currently in fullscreen mode.<br></br>
- `expand`<br></br>
  **type** *`boolean`*<br></br>
  Sets fullscreen mode.<br></br>

**Returns**

`<FieldExtensionProps | interface>`

&nbsp;

&nbsp;


---
# useFormSidebarExtension

Source: https://hygraph.com/docs/app-framework/functions/useformsidebarextension

**useFormSidebarExtension**()<br></br>
Hook function for sidebar elements.

**Properties**

- `extension`<br></br>
  - `config`<br></br>
    **type** *`object`*<br></br>
    Global configuration of the field<br></br>
  - `sidebarConfig`<br></br>
    **type** *`object`*<br></br>
    Configurations that display at the sidebar level<br></br>
- `form`<br></br>
  **type** *`Object` | `Form`*<br></br>
  Contains methods to interact with the content form<br></br>
- `model`<br></br>
  **type** *`Model`*<br></br>
  Details about the current model<br></br>
- `allLocales`<br></br>
  **type** *`Locale`*<br></br>
  Array of locales<br></br>
- `stages`<br></br>
  **type** *`Stage`*<br></br>
  Array of stages<br></br>
- `entry`<br></br>
  - `id`<br></br>
    **type** *`string` | `null`*<br></br>
    Id of the entry<br></br>
  - `createdBy`<br></br>
    **type** *`object`* of type User<br></br>
    Who created the entry<br></br>
  - `updatedBy`<br></br>
    **type** *`object`* of type User<br></br>
    Who updated the entry<br></br>
  - `createdAt`<br></br>
    **type** *`string`*<br></br>
    When it as created<br></br>
  - `updatedAt`<br></br>
    **type** *`string`*<br></br>
    When it was updated<br></br>


**Returns**

`<FormSidebarExtensionProps | interface>`

&nbsp;

&nbsp;


---
# App Framework

Source: https://hygraph.com/docs/app-framework/index

This document helps you understand what the **Hygraph App Framework** is and what you can do with it. With the App Framework, you can extend the core capabilities that Hygraph offers. It gives you the possibility to create your own custom apps, and (optionally) share them with other users.

The **App Framework** is a toolset that allows you to build apps easily. You can use it to build apps that integrate Hygraph with third-party services, or build custom integrations tailored to your specific needs.

<Alert title="Would you like to build your own app" theme="info">

Look into our [App Framework tutorial](/docs/app-framework/first-steps/overview).

</Alert>

## What are apps?

Apps are packages that extend Hygraph in various ways. Apps allow for simpler customization and integration of your project with other tools, products and services. With apps, you can adapt Hygraph to your individual or business needs.

## What can apps do?

With apps, you can extend the out-of-the-box Hygraph functionality and User Interface in various ways. From small custom field extensions to full fledged product integrations, with the App Framework & your custom apps it becomes super easy to extend Hygraph to meet your needs.

Some common use cases are:

- Adding custom fields to your models
- Customizing the content editing sidebar to improve the editor experience
- Triggering actions such as CI builds in third-party systems

For inspiration on what's possible with the App Framework, check out the publicly available apps in our <Link href="https://hygraph.com/marketplace" target="_blank">Marketplace</Link>.

## Key benefits

The App Framework offers more **flexibility** and greater **security features**:

### Flexibility

Creating your own app to be used in the Hygraph platform allows you to have **custom fields** on your setup, as well as **custom functionality** on your CMS. You can even group up all your custom elements under one app and install them at once, which greatly simplifies the installation process compared to UI Extensions.

It also makes it possible for you to create custom page views, which was not possible before.

### Security

Certain resources are critical for an app to work, and should therefore be hidden from users to prevent accidental removal. Our **App Framework** offers a **permissions system**, which allows better control over resources visibility as well as over creating resources on behalf of the user.

With this new permissions system you can create the app establishing which resources should be hidden from users, and also which resources are critical and can't be removed once the app is uninstalled.

## Section contents

This section offers a contents map to help you readily find what you're looking for.

### Getting started

| Document                                               | Contents                                                                                                                              |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| [Overview](/docs/app-framework)                        | Hygraph's App Framework overview.                                                                                                     |
| [Register an app](/docs/app-framework/register-an-app) | Contains all the information you need about the app registration process.                                                             |
| [Using app tokens](/docs/app-framework/app-tokens)     | Contains information on how to exchange a setup code for an app token and use it to authenticate Hygraph API requests.                |
| [Install an app](/docs/app-framework/app-installation) | Contains information on how to install an app in your Hygraph Project.                                                                |
| [Delete an app](/docs/app-framework/delete-an-app)     | Contains information on how to delete an app you've created.                                                                          |

### First steps

This is our App Framework tutorial. Take the first steps into creating an app with field, sidebar, or page elements.

| Document                                                                         | Contents                                                                                           |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Overview](/docs/app-framework/first-steps/overview)                             | App Framework tutorial overview document stating what you will learn as well as the prerequisites. |
| [Register your app](/docs/app-framework/first-steps/register-your-app)           | Contains instructions on how to register your app.                                                 |
| [Develop your app](/docs/app-framework/first-steps/develop-your-application)     | Contains instructions on how to develop an application.                                            |
| [Installation flow](/docs/app-framework/first-steps/develop-installation-flow)   | Contains instructions on how to develop your app's installation flow.                              |
| [Configuration flow](/docs/app-framework/first-steps/develop-configuration-flow) | Contains instructions on how to develop your app's configuration flow.                             |
| [Field element](/docs/app-framework/first-steps/develop-field-element)           | Contains instructions on how to develop a custom field element.                                    |
| [Sidebar element](/docs/app-framework/first-steps/develop-sidebar-element)       | Contains instructions on how to develop a custom sidebar element.                                  |
| [Page element](/docs/app-framework/first-steps/develop-page-element)             | Contains instructions on how to develop a custom page element.                                     |

### Quick starters

| Document                                             | Contents                                                                                              |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [Next.js](/docs/app-framework/quick-starters/nextjs) | Contains instructions on how to build an app with a custom field element using our `Next.js` starter. |

### Field elements

| Document                                                           | Contents                                                                                      |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| [List renderer](/docs/app-framework/field-element/list-renderer)   | Contains instructions on how to enable custom list rendering in your app.                     |
| [Table renderer](/docs/app-framework/field-element/table-renderer) | Contains instructions on defining how custom field values are displayed in the content table. |
| [Declaration](/docs/app-framework/field-element/declaration)       | Contains information about field element declaration properties.                              |

### Sidebar elements

| Document                                                       | Contents                                                           |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| [Declaration](/docs/app-framework/sidebar-element/declaration) | Contains information about sidebar element declaration properties. |

### API Reference

| Document                                                                             | Contents                                                                                                            |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| [Common props](/docs/app-framework/api-reference/api-reference-common)               | App Framework API reference for common props to all elements.                                                       |
| [Field element](/docs/app-framework/api-reference/api-reference-field-element)       | App Framework API reference for field element.                                                                      |
| [Sidebar element](/docs/app-framework/api-reference/api-reference-sidebar-element)   | App Framework API reference for sidebar element.                                                                    |
| [Additional types](/docs/app-framework/api-reference/api-reference-additional-types) | App Framework API reference for additional types. It includes model, form, locale, stage, user, dialog, and toasts. |

### Functions

| Document                                                                         | Contents                                    |
| -------------------------------------------------------------------------------- | ------------------------------------------- |
| [OpenDialog](/docs/app-framework/functions/opendialog)                           | OpenDialog function documentation.          |
| [ShowToast](/docs/app-framework/functions/showtoast)                             | ShowToast function documentation.           |
| [ToastOptions](/docs/app-framework/functions/toastoptions)                       | ToastOptions function documentation.        |
| [useFieldExtension](/docs/app-framework/functions/usefieldextension)             | useFieldExtension hook documentation.       |
| [useFormSidebarExtension](/docs/app-framework/functions/useformsidebarextension) | useFormSidebarExtension hook documentation. |
| [useApp](/docs/app-framework/functions/useapp)                                   | useApp hook documentation.                  |

### Constants

| Document                                             | Contents                                                     |
| ---------------------------------------------------- | ------------------------------------------------------------ |
| [Constants](/docs/app-framework/constants/constants) | List of constants with their descriptions, types, and values. |

### Examples

| Document                                                               | Contents                                                               |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [openAssetPicker](/docs/app-framework/examples/openassetpicker-method) | Contains an example that will help you use the openAssetPicker method. |

### Libraries

| Document                                                          | Contents                             |
| ----------------------------------------------------------------- | ------------------------------------ |
| <Link href="https://www.npmjs.com/package/@hygraph/app-sdk-react" target="_blank">React SDK</Link> | Link to our App Framework React SDK. |
| <Link href="https://www.npmjs.com/package/@hygraph/app-sdk" target="_blank">JavaScript SDK</Link>  | Link to our JavaScript SDK.          |

&nbsp;

&nbsp;


---
# Next.js App Framework starter

Source: https://hygraph.com/docs/app-framework/quick-starters/nextjs

## Overview

In this tutorial you will learn how to create apps using our <Link href="https://github.com/hygraph/hygraph-app-nextjs-quick-start" target="_blank">Hygraph App Next.js starter</Link>.

## What you will build

You will create a simple app that adds a custom string field to your Hygraph project.

## Prerequisites

**Setup**

- You must have a **Hygraph** account. If you don't have one, you can create one <Link href="https://app.hygraph.com/signup" target="_blank">here</Link>.
- You must have a [Hygraph project](/docs/getting-started/fundamentals/quickstart#create-a-project) to test the app in.
- You need the latest LTS version of Node.js installed on your machine. If you don't have it, you can <Link href="https://nodejs.org/en/download/" target="_blank">download it here</Link>

**Knowledge**

- Be familiar with the Hygraph platform. If you're not yet familiar with Hygraph, [check out our quickstart](/docs/getting-started/fundamentals/quickstart#create-a-project).
- Be familiar with JavaScript
- Be familiar with React
- Be familiar with Next.js

## 1. Install the example app

Run the following command to install the app from our boilerplate:

```
npx create-next-app --example https://github.com/hygraph/hygraph-app-nextjs-quick-start docs-example-app
```

This will create an example app called `docs-example-app`.

## 2. Run the project locally

Change directories into our example with `cd docs-example-app`. Optionally, you can do this from the console of your preferred IDE. Just open the project there and you can follow the instructions.

<Alert theme="success">

When you open the project you can see that it already comes with the following template pages for you to use: `_app.tsx`, `field.tsx`, `page.tsx`, `setup.tsx`, `sidebar.tsx`.

</Alert>

Run the following command to run your project locally:

```
yarn dev
```

## 3. Register your app

Open our <Link href="https://app.hygraph.com/apps/new" target="_blank">App registration form</Link> and fill in the following data:

**General**

- **Name:** Docs example
- **Description:** Docs example
- **Avatar URL:** `https://localhost:3001/favicon.ico`
- **API ID:** docs-example-app
- **Setup URL:** `https://localhost:3001/setup`

**Permissions**

For this example, we're only going to set up `Content API` permissions to `Read / write`.

<Alert theme="warning">

Permissions can't be edited after the initial save. Consider this information when creating your own app outside of this quickstart.

</Alert>

**Elements**

This is where we are going to use the examples included in the quickstart to quickly set up our app elements. We're going to create a field element using our quickstart example.

Click on `+ Add element` to start, and fill in the following data:

- **Name:** Field example
- **API ID:** field-example
- **Type:** Select `field` from the dropdown
- **Features:** Select `fieldRenderer` from the dropdown
- **Field type:** Select `STRING` from the dropdown
- **URL:** `https://localhost:3001/field`
- **Description:** This is a field example
- **Config:**

  ```json
  {
    "CUSTOM_SETTING": {
      "type": "string",
      "description": "This is the custom setting description",
      "displayName": "Custom setting"
    }
  }
  ```

To finalize the process, click on the `Register app` button, located at the top right corner of the screen.

A popup will display containing the `Client ID` and `Client secret` keys. You can ignore them for now, and if you need them later, you can find them in the `Permissions` tab of your app form.

Navigate go to the `Sharing` tab of your app form, and copy the `App Sharing` URL. We will use it to install the app in a project.

## 4. Install your app

The process of installing an app has been described in detail [here](/docs/app-framework/app-installation). For this quickstart, you can follow that tutorial from step 2 onwards.

**You're done!** Now if you navigate to the **Schema** builder of your Hygraph project and select a model, you will find the custom field you just created in the `STRING` section of the `Add fields` right sidebar. You can now [add the field to your model](/docs/getting-started/build-content-models), and then [use it in a content entry](/docs/getting-started/content-creation) for the model you configured it for.

## Next steps

Congratulations! Now that you've used our starter to build a custom field for your app, you can follow the same steps to build custom sidebars and app views by just filling in the app registration form accordingly.

You may also be interested in learning how to create custom fields and sidebars from scratch using our step-by-step tutorial. [Click here](/docs/app-framework/first-steps/overview) to know more.

If you have any questions, you're welcome to <Link href="https://hygraph-community.slack.com/" target="_blank">join our community!</Link>


---
# Register an app

Source: https://hygraph.com/docs/app-framework/register-an-app

When you build an app for Hygraph, you must register it in Hygraph Studio.

<Alert theme="warning">

Apps will not work on your local environment because our SDK only runs inside our platform.

</Alert>

To register your application, you first need to navigate to **Your apps**. You can access it from your user settings or from the project directory.

To find it in your user settings, navigate to **User settings > Your apps**.

![Your apps in user settings](/images/docs/app-framework/app-framework-yourapps.png)

To find it in your project directory, click the **Your apps** tab at the top of the screen.

![Your apps in project directory](/images/docs/app-framework/app-framework-yourapps-directory.png)

Click `+ Add new app` to open the <Link href="https://app.hygraph.com/apps/new" target="_blank">App registration form</Link>.

The registration form is divided into four tabs:

- [General](/docs/app-framework/register-an-app#general)
- [Permissions](/docs/app-framework/register-an-app#permissions)
- [Elements](/docs/app-framework/register-an-app#elements)
- [Sharing](/docs/app-framework/register-an-app#sharing)

![App registration form](/images/docs/app-framework/app-framework-form.png)

You will be able to save your app by clicking on the `Register app` button, as long as you provide information in the required fields.

<Alert theme="warning">

When you create your own app, click `Register app` only at the end of the process as some information - such as permissions - can't be edited after the initial save.

</Alert>

## General

![App registration - General](/images/docs/app-framework/app-framework-register-general.png)

- **Name:** Mandatory field. This is the name of your app.
- **Description:** Optional field. Here you can provide a description for what your app does.
- **Avatar URL:** Mandatory field. The avatar URL is the logo that will display next to your app's name. Provide a URL that indicates where your logo is hosted.
- **API ID:** Mandatory field. This is where you write your API ID. The form will let you know if the name is taken. This field only allows alphanumeric characters, underscores and hyphens, and you must start with a lowercase letter. This field becomes read-only once the app is created, and you cannot modify it. API IDs are unique across all applications.
- **Setup URL:** Mandatory field. The setup URL provides the form that displays to users when they install your app for the first time in Hygraph. The form will require some information from the user depending on the characteristics of the app.

Once you've completed all mandatory information, you can move on to the next tab.

## Permissions

This section shows the access details of your app.

![App registration - API and Installation permissions](/images/docs/app-framework/app-framework-register-permissions.png)

<Alert theme="warning">

Setting up your app permissions incorrectly might cause the app to not work when installed.

API permissions are only editable when first creating the app. Once the app has been saved for the first time, they can't be changed.

</Alert>

- **API Permissions:** Use these dropdown menus to select permissions for `Content API`, `Schema`, `Webhooks`, and `User`. Ensure that you set up app tokens if you enable any permissions for apps that need access to the Content API, Management API, or webhooks. See [Use app tokens](/docs/app-framework/app-tokens) for more information.

  - **Content API:** Grants the app permissions regarding the content. For example, a localization app would need `read` permissions to access the content to be submitted, then also `write` permissions to allow the content to be translated.
  - **Schema:** Grants the app permissions regarding the schema of your project. For example, an app that sets up models in your schema which will be ready to be used after the app installation, would need `read / write` permissions.
  - **Webhooks:** Grants the app permissions regarding your project's webhooks. For example, a newsletter app which sets up a webhook during installation that can later be triggered upon a certain action, would require `read / write` permissions.
  - **User:** Grants the permission to read the user ID and their roles and permissions to implement access control features within the app.

- **Installation permissions:** These permissions impact who can access the app. You can use the **App access** dropdown to make the app private or shared. If you select Private, then you can click `+ Add member` below to add a member, or `+ Add project` to add a project. The selected members/projects will be able to install the app.

- **Regenerate Client ID and Client secret:** The Client ID and Client secret are the credentials that allow apps to perform actions on behalf of the user. If you lose or forget them, you can regenerate them after creating the app.
  - Client ID: Unique identifier of your app that is used for authentication and authorization. Your Client ID will only display after the app has been saved for the first time.
  - Client Secret: Used with the Client ID to resolve and grant access to your app. Your Client Secret will only display after the app has been saved for the first time.

![Regenerate Client ID and Client Secret](/images/docs/app-framework/regenerate-keys.png)

- **Transfer app ownership:** An app can only be owned by one person at a time. App owners can hand over ownership to someone else if they won't be able to manage the app anymore. To transfer ownership, click **Transfer ownership**, and provide the email address of the new owner. The new owner receives an email with a confirmation link. As soon as they confirm, the ownership is transferred.

![Transfer app ownership](/images/docs/app-framework/app-framework-transfer-app-ownership.png)

## Elements

![App registration - Elements](/images/docs/app-framework/app-framework-register-elements.png)

The **Elements** section will require different data depending on the element type you select. To start adding elements, click on `+ Add element`:

- **Name:** This is where you write the name of your element.
- **API ID:** This is where you write your element's API ID.
- **Type:** when you create an app, you can have field elements, sidebar elements, or pages.
  - `field`: **Field elements** are custom fields that you can add to a model's fields schema.
  - `formSidebar`: **Sidebar elements** are custom widgets that you can add to a model's sidebar schema.
  - `page`: **Page** adds a section for the app under App views in the Content editor.
- **Features:** This dropdown only displays when `field` is selected as **type**, and allows you to select features for said `field`. One or more features can be selected using the dropdown:
  - `FieldRenderer`: If the feature contains this, it can be rendered for fields.
  - `ListRenderer`: If the feature contains this, it can be rendered for **LIST** fields. Click [here](/docs/app-framework/field-element/list-renderer) to learn more about how it works.
  - `TableRenderer`: If the feature contains this, it can be rendered for **Table Cell**. Click [here](/docs/app-framework/field-element/table-renderer) to learn more about how it works.
- **Field type:** This dropdown only displays when `field` is selected as **type** . It allows you to select how the data will be stored, by selecting one of the standard field types from the dropdown menu.
- **URL:** Indicates where this element is located in the project, its dedicated URL.
- **Description:** It's the description that will appear under your field name in the **Add Field / Sidebar Widgets** section of the **Schema**.
- **Config:** You can have custom settings for elements. This field is completed using a `JSON` object, which is used to declare extra fields the user wants to render in the field or sidebar form.
  - [Click here](/docs/app-framework/field-element/declaration#field-configuration) for detailed information on field configuration.
  - [Click here](/docs/app-framework/sidebar-element/declaration#sidebar-configuration) for detailed information on sidebar configuration.

## Sharing

App sharing enables other users to install your app.

![App registration - Sharing](/images/docs/app-framework/app-framework-register-sharing.png)

After creating an app and saving it for the first time, this section will show the `App Sharing` read-only field, which contains the URL that you can copy to then share your app.

<Alert theme="success">

Alternatively - after the initial save of your app - you can share it by navigating to **User Settings > Your Apps**, locating the card of the app you wish to share, and selecting the `Share app` option that you'll find in the context menu.

</Alert>

## Registration

You can save your app by clicking on the `Register app` button, as long as you provide information in the required fields. We recommend you to click `Register app` only at the end of the process as some information - such as permissions - can't be edited after the initial save.

After you register your app for the first time, the client ID and client secret will be available on the **Permissions** tab of the app.

- **Client ID:** Unique identifier of your app that is used for authentication and authorization. Your `Client ID` will only display after the app has been saved for the first time.
- **Client Secret:** Used with the Client ID to resolve and grant access to your app. Your `Client Secret` will only display after the app has been saved for the first time.

The `Client ID` and `Client secret` are the credentials that allow apps to perform actions on behalf of the user.

If you lose or forget them, you will have the option to regenerate them after app creation.

![Regenerate Client ID and Client Secret](/images/docs/app-framework/regenerate-keys.png)

## Installation

After you've successfully created an app, you will need to install it in order to be able to use it. [This guide](/docs/app-framework/app-installation) contains step-by-step information on how to do this.

## Resources

- [App Framework:](/docs/app-framework) Overview to our **App Framework**, which extends **Hygraph** capabilities, offering the possibility of creating your own custom apps and sharing them with other users.
- [Use app tokens:](/docs/app-framework/app-tokens) How to exchange a setup code for an app token and use it to authenticate Hygraph API requests.
- [Install an app:](/docs/app-framework/app-installation) Step by step guide on how to install an app in your **Hygraph** project.
- [Delete an app:](/docs/app-framework/delete-an-app) Documentation for developers on how to delete an app you have created.
- [First steps:](/docs/app-framework/first-steps/overview) This is our App Framework tutorial, a comprehensive step-by-step guide on how to develop an app with custom field and sidebar elements.
- [Next.js starter:](/docs/app-framework/quick-starters/nextjs) Document that guides you through the process of developing an app with a custom field using our `Next.js` starter.
- [API Reference:](/docs/app-framework/api-reference/api-reference-common) Our App Framework API Reference.


---
# Sidebar element declaration

Source: https://hygraph.com/docs/app-framework/sidebar-element/declaration

## Sidebar element properties

| Key             | Type                           | Description                                              |
| --------------- | ------------------------------ | -------------------------------------------------------- |
| `name`          | `String`                       | Name of Sidebar element                                  |
| `apiId`         | `String`                       | Side element API ID                                      |
| `type`          | Enum(`formSidebar`) (required) | Type of element                                          |
| `URL`           | `String`                       | Sidebar element URL                                      |
| `description`   | `String`                       | Description of Sidebar element                           |
| `sidebarConfig` | `ConfigFields`                 | Optional definition of _instance_ configuration settings |

## Sidebar configuration

This is an example for the `JSON` object for the sidebar configuration:

```json
{
  "CUSTOM_SETTING": {
    "type": "string",
    "description": "Field description",
    "displayName": "testString"
  }
}
```

The schema view of the above example would look as follows:

![fieldConfig example - Sidebar](/images/docs/app-framework/app-framework-rfieldConfig-sidebar.png)

This information will be sent as metadata to the app element, and will display in the schema editor - as part of the custom sidebar widget that it was configured for - and users will be able to add it to their models.

To later retrieve this information, you can do this:

```js
// Reading config data in Sidebar Extension

function SidebarElement() {
  const {
    extension: { fieldConfig },
  } = useFormSidebarExtension();
  const customField = fieldConfig?.CUSTOM_SETTING;

  return <div>{customField}</div>;
}
```


---