docs menu

Visual editing

On a preview of your site, editors can point at a title, an image or a paragraph and open that exact field in the studio. You add one attribute to the elements that show content, and one script to your preview pages.

Mark the elements#

editAttr from @galerne/overlay builds the attribute value from the document and the field path:

bash
npm i @galerne/overlay
tsx
import { editAttr } from '@galerne/overlay'

export function PostHeader({ post, branch }) {
  const at = (path: string) => editAttr(post, path, { project: 'acme', branch })
  return (
    <header>
      <h1 data-galerne-edit={at('title')}>{post.title}</h1>
      <img data-galerne-edit={at('cover')} src={post.cover.url} alt={post.cover.alt} />
      <p data-galerne-edit={at('seo.description')}>{post.seo.description}</p>
    </header>
  )
}

editAttr(doc, path, options) takes the document (it needs _id), a field path in the same form as patch_doc (title, seo.description, content[k3f9].heading), and { project, branch }. The branch defaults to main. The value is project:branch:id:path, each part URL-encoded, so you can also write it by hand.

Load the overlay#

Add the script to preview deployments only:

html
<script src="https://api.galerne.cloud/overlay.js" data-project="acme" defer></script>
AttributeWhat it does
data-projectProject used when an element's attribute leaves the project empty
data-studioStudio URL, when you run your own. Default: the Galerne studio

The script needs no token and reads no content. It only uses the attributes on the page.

What editors see#

Hovering a marked element draws an outline with an edit link. The link, or Alt+click on the element, opens the document in the studio in a new tab, scrolled to that field, on the right branch. A preview that queries a branch (see query API) and passes the same branch to editAttr sends editors to that branch.

Keep the script off your production pages: there, the attribute values do nothing and cost a few bytes.

Inside the studio#

With a preview URL, the document editor shows the site next to the fields. In that pane, the edit link and Alt+click focus the field in the editor instead of opening a new tab. Sites built with the Next.js kit also refresh after each save and send plain clicks on marked elements: galerne.LivePreview loads the overlay and does both, and galerne.editable() returns the attributes with the right project and branch.