Skip to main content

Setup Guide

1. Add the Script​

Add the Verse Frame script from the verse-embedded npm package to your page's <head>:

<script src="https://unpkg.com/verse-embedded@1.1.4/dist/verse-embedded.js"></script>

2. Add Container Elements​

Place <div> elements where you want Verse content to appear. Use HTML attributes to specify what to display.

<div verse-series-slug="your-collection-slug"></div>

This is the recommended approach. The collection slug is the URL path segment from verse.works/series/{slug}.

Embed an Artwork​

<div verse-artwork-id="57883342-1032-4820-b318-b42fa761e1aa"></div>

The artwork ID is a UUID provided by the Verse team or available via the GraphQL API.

Embed a Specific Edition​

<div
  verse-artwork-id="57883342-1032-4820-b318-b42fa761e1aa"
  verse-edition-number="1"
></div>

3. Initialize​

Initialize the library after the DOM is ready:

<script>
  const verseEmbed = new VerseEmbed({
    baseUrl: "https://iframe.verse.works"
  });
  verseEmbed.initialize();
</script>

Constructor Options​

OptionTypeDefaultDescription
baseUrlstringrequiredThe Verse iframe origin URL
minHeightnumber480Minimum height in pixels for the iframe container

HTML Attributes​

AttributeDescription
verse-series-slugCollection slug to embed (recommended)
verse-artwork-idArtwork UUID to embed
verse-edition-numberEdition number (requires verse-artwork-id)
verse-custom-styles-pathURL to a custom CSS file for styling the iframe content

Complete Example​

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My Gallery</title>
  <script src="https://unpkg.com/verse-embedded@1.1.4/dist/verse-embedded.js"></script>
  <style>
    .verse-container {
      max-width: 1200px;
      margin: 0 auto;
      padding: 20px;
    }
  </style>
</head>
<body>
  <div class="verse-container">
    <h1>Featured Collection</h1>
    <div verse-series-slug="fields-by-erik-swahn"></div>
  </div>

  <div class="verse-container">
    <h1>Another Collection</h1>
    <div verse-series-slug="what-can-be-by-addie-wagenknecht"></div>
  </div>

  <script>
    const verseEmbed = new VerseEmbed({
      baseUrl: "https://iframe.verse.works",
      minHeight: 600
    });
    verseEmbed.initialize();
  </script>
</body>
</html>

Origin Allowlist​

The sandbox environment (iframe.demo.verse.works) does not require any allowlisting — it works from any domain, including localhost. Use it freely during development and testing.

Production (iframe.verse.works) requires your domain to be allowlisted. localhost:3000 is allowlisted by default, so you can test against production locally.

For other domains:

  1. Contact the Verse team with your domain (e.g., https://yourdomain.com)
  2. The team will add your origin to the allowlist
  3. Once approved, the iFrames will load on your domain
caution

Production pages must be served over HTTPS. Verse iFrames will not load on plain HTTP pages.

Auto-Resize Behavior​

Verse Frame automatically adjusts the iframe height to match its content using the postMessage API. The container element is updated whenever the content height changes, preventing scrollbars inside the iframe.

The minimum height is controlled by the minHeight constructor option (default: 480px).

Fullscreen Mode​

Some Verse content (e.g., generative artworks) supports fullscreen viewing. When a user enters fullscreen mode, the iframe container expands to fill the viewport. Exiting fullscreen restores the original size.

This is handled automatically — no additional configuration needed.

API Methods​

After initialization, the VerseEmbed instance provides:

MethodDescription
initialize()Scan the DOM for verse-* containers and create iFrames
forceRefreshMeasure()Force the iframe to re-measure and report its height
applyStyles(css)Programmatically apply CSS styles to the iframe content

Debugging​

For development and debugging, use the sandbox iframe origin:

const verseEmbed = new VerseEmbed({
  baseUrl: "https://iframe.demo.verse.works"
});
verseEmbed.initialize();

If your integration also uses the GraphQL API, point it to the sandbox endpoint:

curl -X POST https://demo.verse.works/query \
  -H "Content-Type: application/json" \
  -d '{"query": "{ collectionsPage(request: { first: 5 }) { nodes { name slug } } }"}'

Troubleshooting​

iFrame doesn't load:

  • If using production (iframe.verse.works), check that your domain is on the allowlist
  • If using sandbox (iframe.demo.verse.works), no allowlisting is needed — check other issues first
  • Verify HTTPS is configured in production
  • Check browser console for CORS or security errors

Content appears cut off:

  • The auto-resize uses postMessage — ensure no content security policy blocks it
  • Try increasing minHeight in the constructor

Styles look wrong:

  • Custom CSS via verse-custom-styles-path uses partial class name matching (see Customization)