Hygraph
Docs

#Click to Edit setup

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 Hygraph Preview SDK. 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.
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.
  2. Create a PreviewWrapper component to enable the preview functionality.
  3. Set environment variables.
  4. Add data attributes to content elements.
  5. Set up the Preview widget in Studio.
  6. 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.

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:

#Configuration properties

PropertyRequiredDescription
endpointRequiredYour Hygraph Content API endpoint. See Content API.
studioUrlOptional (recommended)Studio base URL. Defaults to https://app.hygraph.com. Set this if your Studio runs on a regional or custom domain.
onSaveOptionalCallback fired after Studio reports a save. Receives the saved entry ID. Use this to trigger revalidation or a router refresh.
debugOptionalEnables verbose console logging. Useful for diagnosing missing attribute issues.
modeOptionalForces 'iframe', 'standalone', or 'auto'. Auto-detection works for most cases.
overlayOptionalCustomize overlay border color, border width, button background, and button text color.
sync.fieldFocusOptionalSynchronizes field focus between Studio and the preview when an editor selects a field.
sync.fieldUpdateOptionalApplies live field changes to the preview as the editor types. Defaults to false.
allowedOriginsOptionalAdditional 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.

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.
  • 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.
    • 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.

AttributeRequiredDescription
data-hygraph-entry-idRequiredThe content entry ID. Every editable element needs this. Always use the root entry ID, not a component instance ID.
data-hygraph-field-api-idOptionalThe API ID of the field in the schema. Without this, clicking Edit opens the entry without focusing a specific field.
data-hygraph-rich-text-formatOptionalFormat for Rich Text fields. Accepts html, markdown, or text.
data-hygraph-component-chainOptionalJSON array describing the path to a nested component field. See tagging component fields.

data-hygraph-entry-id - Content entrydata-hygraph-entry-id - Content entry

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 - Schemadata-hygraph-field-api-id - Schema

#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.

AttributeDescription
data-hygraph-entry-idThe root content entry ID. Never use a component's own ID here.
data-hygraph-field-api-idThe 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-chainJSON array of { fieldApiId, instanceId } describing the path from root entry to the target field.
  • fieldApiId - The field that contains the nested component.
  • instanceId - Unique identifier of the component instance, as returned in your GraphQL query as described below. This is not the API ID of the component.

Data attributes components markupData attributes components markup

#Query to retrieve instanceId

Retrieve the instanceId using the following query:

#Set up the Preview widget in Studio

If you have already configured a Preview widget for 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 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.

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