react-datocms

Both components work with DatoCMS's responsiveImage GraphQL query to optimize image loading, but they serve different architectural needs:

<RSCImage /> (React Server Component)

• Rendering: Rendered and optionally cached on the server.
• Footprint: Zero JavaScript footprint on the client.
• Lazy Loading: Uses native browser loading="lazy".
• Placeholder: Uses the background of the image itself. Warning: Do not use this for images with alpha channels (transparency), as the placeholder is not removed when the image loads.
• Output: Generates a single <picture /> element.

<Image /> (Client Component)

• Rendering: Runs in the browser.
• Footprint: Includes a JavaScript footprint.
• Lazy Loading: Uses IntersectionObserver, allowing for customizable loading thresholds.
• Placeholder: Supports a smooth cross-fade effect between the placeholder and the original image.
• Output: Generates more complex HTML with multiple elements around the <picture /> element.

import { Image, RSCImage } from 'react-datocms';

// Server Component usage
<RSCImage data={responsiveImageData} />

// Client Component usage
<Image data={responsiveImageData} />

The ContentLink component uses DOM traversal to determine which element becomes the clickable target for Visual Editing when it encounters stega-encoded content. When an element containing stega data is clicked, the library walks up the DOM tree following these rules:

1. Group (data-datocms-content-link-group): If a group is found, the library stops and makes that group element the clickable target.
2. Boundary (data-datocms-content-link-boundary): If a boundary is found, the library stops and makes the starting element (the one containing the stega data) the clickable target, preventing further traversal.
3. Root: If neither is found, the starting element itself becomes the target.

Collision Warning

If multiple stega-encoded strings exist within the same parent element without being wrapped in their own elements, they will all resolve to the same target. The library will log a console warning and the last URL will win. To avoid this, wrap each piece of content in its own element (e.g., a <span>).

<!-- Example of nested groups: inner group wins for its content -->
<div data-datocms-content-link-group>
  <h1>{page.title}</h1> {/* Resolves to outer div if title is stega-encoded */}
  <div data-datocms-content-link-group>
    <p>{page.subtitle}</p> {/* Resolves to inner div if subtitle is stega-encoded */}
  </div>
</div>

<!-- Example of boundary: prevents bubbling to parent group -->
<div data-datocms-content-link-group>
  <h1>{page.title}</h1>
  <section data-datocms-content-link-boundary>
    <span>{page.author}</span> {/* Resolves to the span itself due to boundary */}
  </section>
</div>

Structured Text fields require specific patterns to ensure both the main field and its embedded components (blocks/records) are clickable and point to the correct editor URLs.

Rule 1: Wrap the component in a group

Because stega encoding is often contained within a tiny <span> inside the text, you must wrap the entire StructuredText component in a data-datocms-content-link-group to make the whole area clickable.

Rule 2: Use boundaries for embedded content

Embedded blocks, inline records, and inline blocks have their own unique editing URLs. To prevent clicking them from triggering the parent Structured Text editor, wrap them in a data-datocms-content-link-boundary.

Note: renderLinkToRecord does not require a boundary because record links typically don't introduce a new editing target that would collide with the parent group.

<div data-datocms-content-link-group>
  <StructuredText
    data={page.content}
    renderBlock={({ record }) => (
      <div data-datocms-content-link-boundary>
        <BlockComponent block={record} />
      </div>
    )}
    renderInlineRecord={({ record }) => (
      <span data-datocms-content-link-boundary>
        <InlineRecordComponent record={record} />
      </span>
    )}
    renderInlineBlock={({ record }) => (
      <span data-datocms-content-link-boundary>
        <InlineBlockComponent record={record} />
      </span>
    )}
  />
</div>

To implement responsive images, follow these two steps:

1. Query Data: Use the responsiveImage GraphQL query in your DatoCMS project. This returns optimized thumbnails and metadata.
2. Render Component: Import Image or RSCImage from react-datocms and pass the responsiveImage object to the data prop.

Recommended GraphQL Query Pattern

To get the best performance, use imgixParams: { auto: format }. This allows the browser to request the most efficient format (like AVIF or WebP) without increasing your GraphQL response size.

import React from 'react';
import { Image, RSCImage } from 'react-datocms';

const Page = ({ data }) => (
  <div>
    {/* Uses native loading="lazy" */}
    <RSCImage data={data.blogPost.cover.responsiveImage} />
    
    {/* Uses custom lazy-loading via IntersectionObserver */}
    <Image data={data.blogPost.cover.responsiveImage} />
  </div>
);

const query = gql`
  query {
    blogPost {
      cover {
        responsiveImage(imgixParams: { fit: crop, w: 300, h: 300, auto: format }) {
          src
          srcSet
          width
          height
          alt
          title
          base64
          bgColor
          sizes
        }
      }
    }
  }
`;