Hygraph
Docs

#Click to Edit - Remix

This page walks through implementing Click to Edit in a Remix project using the 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. Examples for other supported frameworks are available at:

#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 your content elements.
  5. Set up the Preview widget in Studio.
  6. Verify the setup.

#Install the Preview SDK

To install the Preview SDK, run the following command:

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:

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

// 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

PropertyRequired / OptionalDescription
endpointRequiredHygraph Content API endpoint. To learn how to retrieve the Content API endpoint, see our docs.
studioUrlOptional (recommended)Studio base URL. Defaults to https://app.hygraph.com. Set this if your Studio runs on a regional or custom domain.
debugOptionalEnables verbose console logs to diagnose attribute issues.
modeOptionalForces a specific mode. Options: 'iframe' | 'standalone' | 'auto'. Auto-detection works for most cases.
onSaveOptionalRuns after Hygraph reports a save and receives the entry ID for targeted revalidation.
overlayOptionalCustomize overlay border and button appearance.
sync.fieldFocusOptionalSynchronizes field focus between Studio and the preview when an editor selects a field.
sync.fieldUpdateOptionalUpdates the preview immediately when field updates happen in Studio. Defaults to false.
allowedOriginsOptionalExtends 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.

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

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.

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

The examples below use a recipe model. To bootstrap the same Hygraph project used here, follow the project setup instructions.

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.

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

// 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:

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

GraphQL query to retrieve instanceId values for basic components:

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.

GraphQL query to retrieve instanceId values for nested components. Extend your basic component query:

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

#Full example

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

#Related docs