Variants

Variants are alternate renditions of one image#

A variant is a derived version of one source image. It has its own URL, dimensions, and file size, but stays connected to the original media item. Variants prevent an editor from uploading the same photo repeatedly just to make a thumbnail, card image, and hero image.

Original product photo
  -> thumbnail  (small square)
  -> medium     (content image)
  -> hero       (wide crop)

What happens after an image upload#

For raster images, Contoprix queues background processing after the upload is stored. With the default server settings, it automatically creates these two variants:

An operator can change the server's variant presets, so treat variant names and dimensions as delivered data rather than permanent constants in your frontend. Variants are not created for PDFs, and SVG uploads are not accepted by the current server.

Because processing is queued, an image can be available before all of its variants appear. Refresh the media details after a short wait instead of assuming a missing rendition means the upload failed.

Create your own variant#

Use the image editor when the automatic set is not enough.

Example: create a banner from a product photo.

1. Open the source image in the Media Library.
2. Crop to the banner's composition.
3. Resize to the component's target size, such as 1600 x 900.
4. Choose a web-friendly output format.
5. Select Save as variant.
6. Use a descriptive variant type such as hero, card, or social.
7. Preview the component before publishing.

If a type name already exists, Contoprix preserves both versions by adding a timestamp suffix to the newer manually created variant. This avoids silently overwriting an existing rendition.

Select a delivered variant in a frontend#

The media delivery endpoint returns the original plus an array of variants. The endpoint needs an API client with the media:read scope:

GET /api/delivery/media/{mediaId}

Keep the request server-side. This small example deliberately uses fetch because the current core SDK's ContoprixMedia type exposes the basic media fields, while the raw delivery response also contains the variants array.

type DeliveredVariant = {
  variantType: string;
  url: string;
  width: number;
  height: number;
  size: number;
};

type DeliveredMedia = {
  id: string;
  url: string;
  width?: number;
  height?: number;
  altText?: string;
  variants: DeliveredVariant[];
};

export async function getDeliveredMedia(mediaId: string): Promise<DeliveredMedia> {
  const response = await fetch(
    new URL(`/api/delivery/media/${encodeURIComponent(mediaId)}`, process.env.CONTOPRIX_BASE_URL!),
    {
      headers: {
        "x-contoprix-delivery-key": process.env.CONTOPRIX_DELIVERY_KEY!,
      },
      cache: "no-store",
    },
  );

  if (!response.ok) throw new Error(`Could not load media (${response.status})`);
  return response.json() as Promise<DeliveredMedia>;
}

Choose a preferred rendition and keep the original as a safe fallback:

type VariantLike = { variantType: string; url: string };

export function selectVariant<T extends VariantLike>(
  variants: T[],
  preferredType: string,
  fallbackUrl: string,
) {
  return variants.find((variant) => variant.variantType === preferredType)?.url ?? fallbackUrl;
}

const imageUrl = selectVariant(media.variants, "hero", media.url);

return <img src={imageUrl} alt={media.altText ?? ""} />;

Regenerate with care#

The Media Library can regenerate an image's variants. Regeneration removes the existing variants for that media item and creates the configured automatic set again. That means a manually created hero or card variant can be removed during regeneration.

Before regenerating:

1. Check which page components use the image.
2. Note any manual variant names and crops you need to preserve.
3. Regenerate only when the original or preset configuration has changed.
4. Recreate or verify custom variants afterward.

Troubleshooting#

For crop, resize, and format choices, continue to Image Processing.