Hygraph Live Preview SDK

Note: Alpha Version
This SDK is currently in early alpha. While functional, it may contain bugs and the API might change without notice.

A library for integrating Hygraph live preview into your frontend applications.

Installation

npm install @hygraph/live-preview-sdk

Usage

React

If you want to use Inspector in a React project, you can use the HygraphInspector component. This can be accessed via the @hygraph/live-preview-sdk/react package.

import React from "react";
import { HygraphInspector } from "@hygraph/live-preview-sdk/react";

const App: React.FC = () => {
  return (
    <div>
      <HygraphInspector endpoint="https://api.hygraph.com/my-project/master">
        <YourChildComponent />
      </HygraphInspector>
    </div>
  );
};

export default App;

Optional: Accessing Inspector Context

If you need to access the inspector's state within your components, you can optionally use the useInspector hook:

import { useInspector } from "@hygraph/live-preview-sdk/react";

const YourChildComponent: React.FC = () => {
  const { isInitialized, endpoint } = useInspector();
  return (
    <div>
      Inspector initialized: {isInitialized ? "Yes" : "No"}, endpoint:{" "}
      {endpoint}
    </div>
  );
};

Custom Data Attributes

To build the link between your frontend application and the Hygraph CMS, you need to add the following data attributes to the elements you want to inspect:

data-hygraph-entry-id
data-hygraph-field-api-id
data-hygraph-entry-locale

A simple example of how to add these attributes to an element could look like this:

<h1
  data-hygraph-entry-id="cm1173r6nbngf07w5kyaxonmb"
  data-hygraph-field-api-id="title"
  data-hygraph-field-locale="en-US"
>
  Hello World
</h1>

For every element you want to enable inspector mode you must at least add the data-hygraph-entry-id attribute. This is the id of the content entry in your project.

There are two more optional attributes:

data-hygraph-field-api-id - This is the API ID of the field you want to inspect. This value is used if you want to focus the field in the CMS content form when you click on the element.

data-hygraph-entry-locale - This is the locale of the field you want to inspect. This value is used to focus the correct locale of the field in case it is localized.

Customizing Styles

You can customize the appearance of both the inspector overlay and its tooltip by passing style options. The style options can be imported from the SDK:

import { HygraphInspectorStyleOptions } from "@hygraph/live-preview-sdk";

The style options are divided into two main sections: overlay and tooltip. Each section has various customizable properties grouped by their purpose:

Overlay Options

Visual Styles

• background: Background color of the overlay (default: 'transparent')
• backgroundOnEnter: Background color when hovering (default: 'rgba(255, 255, 255, 0.1)')
• backgroundOnLeave: Background color after hover (default: 'transparent')
• border: Border style of the overlay (default: '2px dashed rgba(99, 102, 241, 0.2)')
• borderTop: Top border style (default: 'none')
• boxShadow: Box shadow of the overlay
• opacity: Opacity of the overlay

Layout and Positioning

• position: Position of the overlay (default: 'absolute')
• top: Top position (default: '-40px')
• left: Left position (default: '0')
• width: Width of the overlay (default: '100%')
• height: Height of the overlay (default: 'calc(100% + 40px)')

Behavior

• boxSizing: Box sizing behavior (default: 'border-box')
• pointerEvents: Pointer events behavior (default: 'auto')
• transition: Transition effects (default: 'all 0.2s ease-in-out')

Tooltip Options

Position and Layout

• position: Position of the tooltip (default: 'absolute')
• top: Top position (default: '10px')
• left: Left position (default: '10px')
• zIndex: Z-index value (default: '1000')
• display: Display property (default: 'flex')
• alignItems: Alignment of items (default: 'center')
• gap: Gap between items (default: '6px')

Visual Styles

• background: Background color (default: 'rgb(99, 102, 241)')
• backgroundOnEnter: Background color on hover (default: 'rgb(99, 102, 241)')
• backgroundOnLeave: Background color after hover (default: 'rgb(99, 102, 241)')
• color: Text color (default: 'white')
• border: Border style (default: 'none')
• borderRadius: Border radius (default: '6px')
• boxShadow: Box shadow (default: '0 2px 4px rgba(0, 0, 0, 0.1)')
• opacity: Opacity (default: '0')
• visibility: Visibility state (default: 'hidden')

Typography

• fontSize: Font size (default: '13px')
• lineHeight: Line height (default: '1')
• whiteSpace: White space handling (default: 'nowrap')
• fontFamily: Font family (default: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif')
• fontWeight: Font weight (default: '500')

Behavior

• cursor: Cursor style (default: 'pointer')
• pointerEvents: Pointer events behavior (default: 'auto')
• transition: Transition effects (default: 'all 0.2s ease-in-out')
• padding: Padding (default: '8px 12px')

Example usage:

const styleOptions: HygraphInspectorStyleOptions = {
  overlay: {
    background: 'rgba(0, 0, 0, 0.05)',
    border: '2px dashed blue',
    backgroundOnEnter: 'rgba(0, 0, 0, 0.1)'
  },
  tooltip: {
    background: '#333',
    color: '#fff',
    borderRadius: '8px',
    fontSize: '14px'
  }
};

<HygraphInspector 
  endpoint="https://api.hygraph.com/my-project/master"
  styleOptions={styleOptions}
>
  <YourChildComponent />
</HygraphInspector>

All style options are optional and will fall back to their default values if not provided.