Work with DAM assets

When DAM integration is enabled in your CMS instance, you get helper functions for working with images, media, and files from Optimizely's Content Marketing Platform. These utilities handle preview tokens, generate responsive image markup, and manage alt text automatically.

📘
Note
These utilities only work when DAM assets are enabled in your Content Graph. Check with your CMS administrator if you're not sure whether the integration is active.

The SDK includes the following helpers:

damAssets() - Returns pre-configured helpers for the content property
getSrcset() - Builds responsive srcset strings from renditions
getAlt() - Pulls alt text from assets (with fallback support)

Use `damAssets()`

Use damAssets() to access DAM helper functions for a content instance. This function automatically applies preview tokens when editors view content in preview mode.

import { damAssets } from '@optimizely/cms-sdk';

export default function HeroComponent({ opti }) {
  const { src } = getPreviewUtils(opti);
  const { getSrcset, getAlt } = damAssets(opti);

  return (
    <img
      src={src(opti.heroImage)}
      srcSet={getSrcset(opti.heroImage)}
      sizes="(max-width: 768px) 100vw, 50vw"
      alt={getAlt(opti.heroImage, 'Hero image')}
    />
  );
}

Generate responsive images with `getSrcset()`

getSrcset() builds a valid srcset attribute from the renditions defined on a DAM asset.

Filters out duplicate widths (keeps the first one)
Adds preview tokens automatically in edit mode
Returns undefined if there are no renditions

import { damAssets } from '@optimizely/cms-sdk';

export default function ProductImage({ opti }) {
  const { src } = getPreviewUtils(opti);
  const { getSrcset } = damAssets(opti);

  return (
    <img
      src={src(opti.productImage)}
      srcSet={getSrcset(opti.productImage)}
      sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
      alt="Product image"
    />
  );
}

The generated srcset will look like:

https://example.dam.optimizely.com/image1.jpg 100w, 
https://example.dam.optimizely.com/image2.jpg 500w, 
https://example.dam.optimizely.com/image3.jpg 1000w

`getAlt()`

getAlt() resolves alt text using the following priority order:

Asset's AltText property if it exists
Your fallback text
An empty string for decorative images

import { damAssets } from '@optimizely/cms-sdk';

export default function ImageComponent({ opti }) {
  const { src } = getPreviewUtils(opti);
  const { getAlt } = damAssets(opti);

  return <img src={src(opti.image)} alt={getAlt(opti.image)} />;
}

Provide fallback alt text:

import { damAssets } from '@optimizely/cms-sdk';

export default function BannerComponent({ opti }) {
  const { src } = getPreviewUtils(opti);
  const { getAlt } = damAssets(opti);

  return (
    <img
      src={src(opti.bannerImage)}
      alt={getAlt(opti.bannerImage, 'Marketing banner')}
    />
  );
}

For decorative images:

If no alt text exists on the asset, getAlt() returns an empty string.

const { src } = getPreviewUtils(opti);
const { getAlt } = damAssets(opti);

// Will render alt="" if no AltText exists in the asset
<img src={src(opti.decorativeIcon)} alt={getAlt(opti.decorativeIcon)} />;

📘
Note
Avoid omitting fallback text unless the image is purely decorative. Empty alt text signals assistive technologies to ignore the image.

Use DAM assets with Next.js image optimization

When using Next.js, configure your DAM hostname in remotePatterns. Without this configuration, Next.js does not optimize DAM-hosted images.

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '*.cms.optimizely.com',
      },
      {
        protocol: 'https',
        hostname: '*.cmstest.optimizely.com',
      },
      {
        protocol: 'https',
        hostname: 'your-dam-instance.optimizely.com', // Replace with your hostname
      },
    ],
  },
};

export default nextConfig;

Then use the Next.js Image component normally:

import Image from 'next/image';
import { damAssets } from '@optimizely/cms-sdk';

export default function OptimizedImage({ opti }) {
  const { src } = getPreviewUtils(opti);
  const { getSrcset, getAlt } = damAssets(opti);

  return (
    <Image
      src={src(opti.image)}
      alt={getAlt(opti.image, 'Default alt text')}
      width={800}
      height={600}
      srcSet={getSrcset(opti.image)}
      sizes="(max-width: 768px) 100vw, 50vw"
    />
  );
}

Complete example

import { damAssets } from '@optimizely/cms-sdk';
import Image from 'next/image';

type Props = {
  opti: Infer<typeof ArticleContentType>;
};

export default function ArticleHero({ opti }: Props) {
  const { src } = getPreviewUtils(opti);
  const { getSrcset, getAlt } = damAssets(opti);

  return (
    <article>
      <header>
        <h1>{opti.title}</h1>

        {/* Primary hero image with responsive srcset */}
        <Image
          src={src(opti.heroImage)}
          alt={getAlt(opti.heroImage, 'Article hero image')}
          width={1200}
          height={600}
          srcSet={getSrcset(opti.heroImage)}
          sizes="100vw"
          priority
        />
      </header>

      <div>
        {/* Thumbnail image */}
        <img
          src={src(opti.thumbnail)}
          srcSet={getSrcset(opti.thumbnail)}
          sizes="(max-width: 768px) 100px, 200px"
          alt={getAlt(opti.thumbnail)}
        />

        <div>{opti.summary}</div>
      </div>
    </article>
  );
}

Note

Use damAssets()

Generate responsive images with getSrcset()

getAlt()

Note

Use DAM assets with Next.js image optimization

Complete example

Use `damAssets()`

Generate responsive images with `getSrcset()`

`getAlt()`