Web components

Click Flip

What it does: Flips between the two images when clicked.

Use case: Ideal for quickly comparing visual states like before/after restoration or edits.

<vgg-image-compare
  mode="clickflip"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Color Diff

What it does: Highlights pixel-level color differences between the fixed and moving image.

Use case: Good for evaluating color corrections or compression artifacts.

<vgg-image-compare
  mode="colordiff"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Difference

What it does: Calculates and displays the per-pixel color difference between the two aligned images. The result highlights areas where the images differ visually.

Use case: Useful for spotting subtle changes between two versions of the same image — e.g. in conservation, retouching, or quality assurance. Best used when the images are nearly identical except for small edits or degradations.

<vgg-image-compare
	mode="difference"
	configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Edge

What it does: Extracts and overlays edges to show significant visual structure changes.

Use case: Useful for structural comparisons such as changes in layout, text, or contour.

<vgg-image-compare
  mode="edge"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Fade

What it does: Fades gradually between the two aligned images as you move the mouse over the image area. The opacity of the top image changes based on cursor position.

Use case: Useful for smoothly comparing changes between two versions, such as restoration work, retouching, or alterations that affect the overall tone or lighting. Helps users perceive gradual differences without abrupt transitions.

<vgg-image-compare
	mode="fade"
	configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Flicker mode

What it does: Flickers between the two images rapidly, useful for spotting subtle changes or misalignments.

Use case: Helps with alignment tasks or detecting inconsistencies between two versions of the same layout.

<vgg-image-compare mode="flicker" 
  configUrl="https://abitofcode.com/images/puzzle.json"></vgg-image-compare>

Hover

What it does: Displays one image by default, and switches to the second image when the mouse hovers over the comparison area.

Use case: Ideal for highlighting subtle or dramatic changes, such as annotations, restorations, or damage repairs. Allows users to quickly toggle views by simply moving the mouse in and out.

<vgg-image-compare
  mode="hover"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Lens Zoom

What it does: Shows a zoomed-in circular lens that follows the cursor. One image is displayed normally, while the other is shown inside the zoom lens for detailed comparison.

Use case: Perfect for inspecting fine details, such as print quality, stitching, small text, or texture differences between two aligned images. Great for quality assurance or scholarly review.

<vgg-image-compare
  mode="lenszoom"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Overlay

What it does: Shows one image over the other with adjustable opacity.

Use case: Helpful when you want to superimpose a change and adjust visibility between two layers.

<vgg-image-compare
  mode="overlay"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Paint

What it does: Allows users to "paint" over the base image with the second image using their mouse or finger. Only the areas painted are revealed.

Use case: Useful for exploratory comparison, letting users gradually uncover specific areas of interest—ideal in presentations or when demonstrating localized differences such as retouching, restoration, or hidden features.

<vgg-image-compare
  mode="paint"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Reveal

What it does: Displays the first image fully, then reveals the second image from left to right (or top to bottom) as the user moves their mouse or finger across the canvas.

Use case: Great for showcasing progressive changes—like before-and-after restoration—or for inviting users to interactively uncover details hidden beneath the surface.

<vgg-image-compare
  mode="reveal"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Slide

What it does: This mode lets the user drag a vertical slider across the image to compare the 'fixed' and 'moving' images.

Use case: Great for subtle visual changes like retouching, image restoration, or comparing manuscripts before and after conservation.

<vgg-image-compare
  mode="slide"
  configUrl="https://abitofcode.com/images/ex3.json"
></vgg-image-compare>

Toggle

What it does: Switches instantly between the two images when clicked, without animation.

Use case: Best for simple A/B comparisons where rapid switching helps the viewer notice differences, especially in structural or color changes.

<vgg-image-compare
  mode="toggle"
  configUrl="https://abitofcode.com/images/ex1.json"
></vgg-image-compare>

Switching modes

There is a selector here

A mode selector is provided using the <vgg-mode-selector> element. It is linked to the comparison component by referencing its id via the target attribute. When the selected value changes, it updates the mode attribute on the target <vgg-image-compare>.

<vgg-image-compare id="compare-1" mode="slide"
    configUrl="https://abitofcode.com/images/ex2.json"></vgg-image-compare>
<p>There is a selector here <vgg-mode-selector target="compare-1"></vgg-mode-selector></p>

Required Script Includes

To use the <vgg-image-compare> web component and the <vgg-mode-selector>, you need to include their JavaScript files in your HTML. Make sure to set the correct paths to the scripts based on where they are hosted on your server.

If the scripts are located at the root of your site, you can include them like this:

<script type="module">
	import '/vgg-image-compare.js';
	import '/vgg-mode-selector.js';
</script>

If the files are in a subdirectory (e.g., /scripts/), update the paths accordingly:

<script type="module">
	import '/scripts/vgg-image-compare.js';
	import '/scripts/vgg-mode-selector.js';
</script>

Creating a Transformation File

To use the <vgg-image-compare> component, you need a transformation file in JSON format that describes how to align two images. You can create this file using the Image Compare Workbench tool: https://image-compare-workbench-9c18d4.gitlab.io/

Steps to Create the JSON File

Open the tool in your browser.
Click Upload Fixed Image to load the base image.
Click Upload Moving Image to load the image you want to align with the base.
Click the Compare button. The tool will automatically align the images using geometric registration.
Once aligned, click Export and choose JSON to download the transformation data.
Upload the exported JSON file to the same domain where your web page and images are hosted (e.g. https://yourdomain.com/images/puzzle.json).

Important Notes

The images section in the exported JSON must include full URLs pointing to where the images will be served.
The domain in the image URLs must match the domain serving your page to avoid CORS or Mixed Content issues.

The size of the <vgg-image-compare> component is determined by the dimensions of the fixed (or base/reference) image defined in the JSON file. This image sets the coordinate system for all comparisons, so all other images and transformations are aligned to match its resolution. To avoid unexpected layout issues, ensure the fixed image has the desired display size and aspect ratio.

Example JSON

{
	"version": "1.0.0",
	"images": {
		"case6-puzzle-1-a.jpg": "https://abitofcode.com/images/case6-puzzle-1-a.jpg",
		"case6-puzzle-1-b.jpg": "https://abitofcode.com/images/case6-puzzle-1-b.jpg"
	},
	"registration": [
		{
			"fixed": "case6-puzzle-1-a.jpg",
			"moving": "case6-puzzle-1-b.jpg",
			"fixed_crop": [0, 0, 1, 1],
			"moving_crop": [0, 0, 1, 1],
			"transform": "data:application/octet-stream;base64,...",
			"inverse_transform": "data:application/octet-stream;base64,...",
			"base_transform": "data:application/octet-stream;base64,...",
			"type": "affine"
		}
	],
	"luminance": {
		"case6-puzzle-1-a.jpg": [62.68, 32.51],
		"case6-puzzle-1-b.jpg": [62.68, 32.74]
	}
}

Once hosted, you can load this transformation by setting the configUrl attribute in your component:

<vgg-image-compare
	mode="slide"
	configUrl="https://abitofcode.com/images/puzzle.json">
</vgg-image-compare>