Content Image

ContentImage renders images that participate in document flow - the image controls its own dimensions and pushes surrounding content out of the way, just like a paragraph or heading. No object-fit styling is applied; the image renders at its natural aspect ratio.

Use ContentImage when the image is the content: article photos, product shots, thumbnails, inline figures, or any image whose intrinsic size matters to the layout.

ContentImage vs CoverImage

ContentImage - the image controls its size (inline flow, natural aspect ratio). CoverImage - the container controls the size (backdrop, object-fit: cover, crops to fill).

If your image sits inside a fixed-height box and content overlays it, you want CoverImage. If the image flows naturally alongside text, you want ContentImage.

npx shadcn@latest add @rokkit200-ui/content-image

Preview

The image below flows naturally within the article body. It renders at its intrinsic aspect ratio and the surrounding text wraps around it - the image controls its own size.

This is a ContentImage - use it when the image is the content: article photos, product shots, thumbnails, or any image that participates in document flow.

Code

import { ContentImage } from "@/registry/rokkit200-ui/components/content-image/content-image";
import type {
    ImageUrlBuilder,
    NormalizedImageSource,
    PictureProfile,
    UrlTransform,
} from "@/registry/rokkit200-ui/components/image/image-types";

/**
 * A demo-only URL builder for placehold.co that rewrites the path-encoded
 * dimensions and appends a text label showing the requested width.
 * This makes each srcset candidate visually distinct so you can resize
 * the browser and see the browser pick a different resolution.
 */
const placeholdDemoBuilder: ImageUrlBuilder = {
    canHandle: image => {
        try {
            return new URL(image.src).hostname.endsWith("placehold.co");
        } catch {
            return false;
        }
    },
    build: (image, transform: UrlTransform) => {
        try {
            const url = new URL(image.src);
            const w = (transform.width as number | undefined) ?? image.width;
            const h =
                (transform.height as number | undefined) ??
                (w != null && image.width && image.height
                    ? Math.round(w * (image.height / image.width))
                    : image.height);

            // Rewrite the leading /WxH segment
            url.pathname = url.pathname.replace(/^\/\d+x\d+/, `/${w}x${h}`);

            // Stamp the requested width as visible text on the placeholder
            url.searchParams.set("text", `${w}x${h}`);

            return url.toString();
        } catch {
            return image.src;
        }
    },
};

const image: NormalizedImageSource = {
    src: "https://placehold.co/800x500",
    width: 800,
    height: 500,
    metadata: {
        alt: "Photograph of a mountain landscape used as an inline content image",
    },
};

const profile: PictureProfile = {
    id: "content-default",
    srcSetWidths: [400, 600, 800],
    sizes: ["(max-width: 600px) 100vw", "800px"],
};

/**
 * ContentImage renders an inline, document-flow image whose dimensions are
 * controlled by the image itself - not by its container. The image pushes
 * surrounding content out of the way, just like a paragraph or heading.
 *
 * Typical uses: article photos, product shots, thumbnails, inline figures.
 */
export default function ContentImageDefaultDemo() {
    return (
        <article className="text-muted-foreground mx-auto max-w-prose space-y-4 text-sm">
            <p>
                The image below flows naturally within the article body. It renders at
                its intrinsic aspect ratio and the surrounding text wraps around it -
                the image controls its own size.
            </p>
            <ContentImage
                imageSource={image}
                profile={profile}
                urlBuilder={placeholdDemoBuilder}
                className="rounded-lg"
            />
            <p>
                This is a <strong>ContentImage</strong> - use it when the image{" "}
                <em>is</em> the content: article photos, product shots, thumbnails, or
                any image that participates in document flow.
            </p>
        </article>
    );
}

Examples

Art Directed

Art-directed content images use <picture> with multiple sources. The imageClassName prop targets the inner <img> element while className applies to the <picture> wrapper. For more on Art Directed images and the <picture> element, see here.

Preview

Code

import { ContentImage } from "@/registry/rokkit200-ui/components/content-image/content-image";
import type {
    ArtDirectedImageSource,
    ImageUrlBuilder,
    PictureProfile,
    UrlTransform,
} from "@/registry/rokkit200-ui/components/image/image-types";

/**
 * Demo-only placehold.co builder - rewrites the path dimensions and stamps
 * the requested size as visible text so each srcset candidate is distinct.
 */
const placeholdDemoBuilder: ImageUrlBuilder = {
    canHandle: image => {
        try {
            return new URL(image.src).hostname.endsWith("placehold.co");
        } catch {
            return false;
        }
    },
    build: (image, transform: UrlTransform) => {
        try {
            const url = new URL(image.src);
            const w = (transform.width as number | undefined) ?? image.width;
            const h =
                (transform.height as number | undefined) ??
                (w != null && image.width && image.height
                    ? Math.round(w * (image.height / image.width))
                    : image.height);

            url.pathname = url.pathname.replace(/^\/\d+x\d+/, `/${w}x${h}`);
            url.searchParams.set("text", `${w}x${h}`);

            return url.toString();
        } catch {
            return image.src;
        }
    },
};

type ProfileKey = "default" | "desktop" | "tablet" | "mobile";

const artDirectedSources: ArtDirectedImageSource<ProfileKey> = {
    fallback: {
        src: "https://placehold.co/800x600",
        width: 800,
        height: 600,
        metadata: { alt: "Art-directed content image" },
    },
    sources: [
        {
            media: "(min-width: 1920px)",
            image: {
                src: "https://placehold.co/1920x1080",
                width: 1920,
                height: 1080,
            },
            profileKey: "desktop",
        },
        {
            media: "(min-width: 1280px)",
            image: {
                src: "https://placehold.co/1280x800",
                width: 1280,
                height: 800,
            },
            profileKey: "tablet",
        },
        {
            media: "(min-width: 768px)",
            image: {
                src: "https://placehold.co/768x480",
                width: 768,
                height: 480,
            },
            profileKey: "mobile",
        },
    ],
};

const profileMap: Record<ProfileKey, PictureProfile> = {
    default: {
        id: "art-fallback",
        srcSetWidths: [400, 600, 800],
        sizes: ["100vw"],
    },
    desktop: {
        id: "art-desktop",
        srcSetWidths: [1280, 1600, 1920],
        sizes: ["100vw"],
    },
    tablet: {
        id: "art-tablet",
        srcSetWidths: [768, 1024, 1280],
        sizes: ["100vw"],
    },
    mobile: {
        id: "art-mobile",
        srcSetWidths: [480, 600, 768],
        sizes: ["100vw"],
    },
};

export default function ContentImageArtDirectedDemo() {
    return (
        <ContentImage
            artDirectedImageSource={artDirectedSources}
            profileMap={profileMap}
            urlBuilder={placeholdDemoBuilder}
            className="overflow-hidden rounded-lg"
            imageClassName="w-full object-cover"
        />
    );
}

srcSet Override

Bypass the planner-generated srcset with a pre-built string (e.g. from a CMS). Width descriptors are validated against resolvable sizes - if sizes cannot be resolved, the override is discarded with a dev warning.

Preview

Code

import { ContentImage } from "@/registry/rokkit200-ui/components/content-image/content-image";
import type {
    NormalizedImageSource,
    PictureProfile,
} from "@/registry/rokkit200-ui/components/image/image-types";

const image: NormalizedImageSource = {
    src: "https://placehold.co/800x500",
    width: 800,
    height: 500,
    metadata: {
        alt: "Content image with a CMS-provided srcSet override",
    },
};

/**
 * Profile with empty srcSetWidths - the planner won't generate its own srcset.
 * Sizes are still required so the overridden width-descriptor srcset works.
 */
const profile: PictureProfile = {
    id: "srcset-override",
    srcSetWidths: [],
    sizes: ["(max-width: 600px) 100vw", "800px"],
};

/**
 * A pre-built srcset string, as might be provided by a CMS.
 * Because it uses width descriptors (`w`), ContentImage validates that
 * sizes are resolvable before forwarding the override to the planner.
 */
const cmsSrcSet = [
    "https://placehold.co/400x250 400w",
    "https://placehold.co/600x375 600w",
    "https://placehold.co/800x500 800w",
].join(", ");

export default function ContentImageSrcSetOverrideDemo() {
    return (
        <ContentImage
            imageSource={image}
            profile={profile}
            srcSetOverride={cmsSrcSet}
        />
    );
}

Warning: Empty alt Text

A non-decorative image with no alt text triggers a dev warning. Either provide an alt prop, populate metadata.alt on the source, or mark the image as decorative.

Preview

Code

import { ContentImage } from "@/registry/rokkit200-ui/components/content-image/content-image";
import type {
    NormalizedImageSource,
    PictureProfile,
} from "@/registry/rokkit200-ui/components/image/image-types";

/**
 * Image with no alt text in metadata and no alt prop override.
 * The planner emits a dev warning for non-decorative images with empty alt.
 *
 * Open the browser console to see:
 *   [image] Non-decorative image has empty alt text.
 */
const image: NormalizedImageSource = {
    src: "https://placehold.co/600x400",
    width: 600,
    height: 400,
};

const profile: PictureProfile = {
    id: "warn-empty-alt",
    srcSetWidths: [300, 600],
    sizes: ["(max-width: 600px) 100vw", "600px"],
};

export default function ContentImageWarnEmptyAltDemo() {
    return <ContentImage imageSource={image} profile={profile} />;
}

Warning: Missing Dimensions

An image without width / height triggers a dev warning. Pass suppressMissingDimensionsWarning for intentionally dimension-free images such as SVGs or data URIs.

Preview

Code

import { ContentImage } from "@/registry/rokkit200-ui/components/content-image/content-image";
import type {
    NormalizedImageSource,
    PictureProfile,
} from "@/registry/rokkit200-ui/components/image/image-types";

/**
 * Image deliberately missing width and height - common for SVGs or data URIs.
 * The planner emits a dev warning when dimensions are absent.
 *
 * Open the browser console to see:
 *   [image] Image is missing width.
 */
const image: NormalizedImageSource = {
    src: "https://placehold.co/600x400",
    metadata: {
        alt: "Image without explicit dimensions",
    },
};

const profile: PictureProfile = {
    id: "warn-missing-dims",
    srcSetWidths: [300, 600],
    sizes: ["(max-width: 600px) 100vw", "600px"],
};

export default function ContentImageWarnMissingDimensionsDemo() {
    return <ContentImage imageSource={image} profile={profile} />;
}

Warning: Missing Sizes

A profile with srcSetWidths but no sizes causes the planner to discard the generated srcset and emit a dev warning. Provide sizes on the profile or via the sizes prop.

Preview

Code

import { ContentImage } from "@/registry/rokkit200-ui/components/content-image/content-image";
import type {
    NormalizedImageSource,
    PictureProfile,
} from "@/registry/rokkit200-ui/components/image/image-types";

/**
 * Profile with srcSetWidths but no sizes. When w descriptors are generated
 * but sizes cannot be resolved, the planner discards the srcset and emits
 * a dev warning.
 *
 * Open the browser console to see:
 *   [image] Profile "warn-missing-sizes" has no sizes defined and no sizes
 *   override was provided. srcset with w descriptors requires sizes -
 *   srcset will be omitted.
 */
const image: NormalizedImageSource = {
    src: "https://placehold.co/600x400",
    width: 600,
    height: 400,
    metadata: {
        alt: "Image with a profile missing sizes",
    },
};

const profile: PictureProfile = {
    id: "warn-missing-sizes",
    srcSetWidths: [300, 600],
    sizes: [],
};

export default function ContentImageWarnMissingSizesDemo() {
    return <ContentImage imageSource={image} profile={profile} />;
}

Usage

Below is an example of how to use ContentImage in your site.

import { ContentImage } from "@/rokkit200-ui/components/content-image/content-image";

{/* Inline image in an article - the image controls its own size */}
<ContentImage
    imageSource={{
        src: "/photos/article-photo.jpg",
        width: 800,
        height: 500,
        metadata: { alt: "Article photo" },
    }}
    profile={{
        id: "content",
        srcSetWidths: [400, 600, 800],
        sizes: ["(max-width: 600px) 100vw", "800px"],
    }}
/>

API Reference

Normalized (single-source) props

Prop	Type	Default	Description
imageSource	NormalizedImageSource	—	The image data object (src, width, height, metadata). Required (XOR with art-directed props).
profile	PictureProfile	—	Responsive profile controlling srcset widths, sizes, format, quality, and fit. Required with imageSource.
sizes	string	—	Override sizes from the profile for this specific instance. Optional.

Art-directed (multi-source) props

Prop	Type	Default	Description
artDirectedImageSource	ArtDirectedImageSource<K>	—	Fallback image plus breakpoint-specific sources for <picture> rendering. Required (XOR with normalized props).
profileMap	Record<K, PictureProfile>	—	Map of profile keys to profiles, one per source entry. Required with artDirectedImageSource.

Common props

Prop	Type	Default	Description
alt	string	—	Override alt text. Falls back to imageSource.metadata.alt. Optional.
decorative	boolean	false	Mark as decorative (renders alt=""). Optional.
loading	"lazy" | "eager"	"lazy"	HTML loading strategy. Optional.
fetchPriority	"high" | "low" | "auto"	—	Fetch priority hint for the browser. Optional.
decoding	"async" | "sync" | "auto"	"async"	Decoding strategy. Defaults to async for content images. Optional.
urlBuilder	ImageUrlBuilder	passthrough	CDN-specific URL builder. Optional.
className	string	—	Applied to the outermost element (<img> or <picture>). Optional.
style	React.CSSProperties	—	Inline styles on the outermost element. Optional.
imageClassName	string	—	Applied to the <img> inside <picture> (art-directed only). Optional.
imageStyle	React.CSSProperties	—	Inline styles on the <img> inside <picture>. Optional.
srcSetOverride	string	—	Bypass planner-generated srcset with a pre-built string. Width descriptors require resolvable sizes or the override is discarded. Optional.
suppressWarnings	boolean	false	Silence all dev warnings. Optional.
suppressMissingDimensionsWarning	boolean	false	Silence the missing-dimensions warning only. Optional.
suppressMissingSizesWarning	boolean	false	Silence the missing-sizes warning only. Optional.
suppressEmptyAltWarning	boolean	false	Silence the empty-alt warning only. Optional.