Image comparison

To compare to images with a slider, use HTML with a canvas element of class, "image-comparison". Place the two images to compare as HTML img tags inside the canvas element. The first image is shown on the left of the divider.

You can add a caption in the usual markdown manner, with a <br /> element followed by italics. Image title text is used as a label on the images.

Alt text on the img tags is inaccessible unless the browser session does not support canvas tags (in which case the img tags and any other child elements appear on the page directly). To make the canvas accessible to screen readers and other assistive technologies, add the attributes, role="img" and aria-label="Descriptive text". Refer to Accessibility for more information.

For example:

<canvas class="image-comparison" role="img" aria-label="Compares color versus black-and-white treatments of an image.">
    <img src="Images/img-2509.jpg" title="In living color">
    <img src="Images/img-2509-bw.jpg" title="Black and white">
</canvas>
<br />_Drag the slider to compare the images._

which displays as:

_Drag the slider to compare the images._

Note

In the package docs layout, the canvas is scaled to fit the content area width. With plenty of space, this width is 699 pixels. As the reader makes their browser narrower, the column width decreases first to 533 pixels and then to 425 pixels. If the reader decreases the browser window even farther, the Table of Contents column is turned off, which provides more space for the content column. The content width jumps up to 705 pixels and scales down proportionaly as the browser window narrows to a minimum of about 438 pixels. Future CSS changes could affect these numbers.

Examples and counter examples

Here's another example with a different image to show how the dividing line shows up over different colors:

_Drag the slider to compare the images._

More than two images

Any images beyond the first two are ignored. If the browser doesn't support the canvas (all common browsers do), the images are shown one after the other, along with any other HTML content inside the canvas element. (This is standard HTML behavior.)

An example with four images:

<canvas class="image-comparison" role="img">
    <img src="Images/img-2509.jpg" title="Original">
    <img src="Images/img-2509-bw.jpg" title="Heavy-handed sharpening">
    <img src="Images/ColorBiasAndScaleExample.png" title="I'm an ignored image">
    <img src="Images/ColorBiasAndScaleExample-inverse.png" title="I'm also ignored">
</canvas>
<br />_This canvas has four images. Only the first two matter._

_This canvas has four images. Only the first two matter._

Not enough images

An example with too few images:

_This canvas has no images._

If a canvas has one or zero images, nothing is shown, but the canvas element still takes up space on the page. (This is default HTML behavior.)

Different aspect ratios

The size and aspect ratio of the canvas is based on the first image. Both images should be the same aspect ratio; otherwise, this happens:

_This canvas has two images with different aspect ratios._

Narrow images

This example shows a comparison of two images with a portrait aspect ratio with a width smaller than the max display width on the doc page (just to make sure it works properly):

_Smaller width with portrait aspect ratio_

Accessibility

To enhance accessibility, add the attributes, role="img" and aria-label="Descriptive text", to the canvas element. The descriptive text is read by screen readers and other assistive technologies.

You can also add fallback text content inside the canvas element, which is shown if the browser doesn't support the canvas element. For example:

<canvas class="image-comparison" role="img" aria-label="Compares color versus black-and-white treatments of an image.">
    <img src="Images/img-2509.jpg" title="In living color" alt="A color image.">
    <img src="Images/img-2509-bw.jpg" title="Black and white" alt="The same image converted to black-and-white with the BW filter.">
    <p>By applying the BW filter, the color values in an image are converted to monochrome based on their luminance value.</p>
</canvas>
<br />_Drag the slider to compare the images._