<image-comparison>

Compare two images using a slider, an overlay, or a side by side split view.
This webcomponent follows the open-wc recommendation.

image-comparison.mp4

SRT file for captions

Features

• three variants available: slider, overlay, split
• Right-to-left language support (document's dir attribute set to ltr/rtl)
• Keyboard controls:
  • Slider:
    • ← / → move in small steps
    • Shift + ←/→ for increased steps
    • (Home / Pos1) / End, ⌘/Ctrl + ←/→ to jump left or right
  • Overlay: when in focus press and hold Enter / Space
• Custom events
• Support for labels and custom prompts
• Further customization through CSS variables
• Runs ✨everywhere✨ because it's a webcomponent

Installation

npm i image-comparison-component

Usage

Import

// Script
<script type="module">
  import 'image-comparison/image-comparison.js';
</script>

// Bundler
import 'image-comparison/image-comparison.js';

HTML

The general structure always follows the scheme below. The only thing that always needs to be adjusted is the "variant" attribute. Further customization through attributes.

<image-comparison variant="slider">
  <label slot="label-before">Original</label>
  <label slot="label-after">Vogue Filter</label>

  <img slot="image-before" src="kasimir.jpg" alt="kasimir" />
  <img
    slot="image-after"
    src="kasimir_filter.jpg"
    alt="kasimir with the vogue filter applied"
  />
</image-comparison>

Slider

The "slider" variant lets you compare your images by dragging a slider. You can also just click or tap somewhere or use its keyboard controls

• ← / → move in small steps
• Shift + ←/→ for increased steps
• (Home / Pos1) / End, ⌘/Ctrl + ←/→ to jump left or right

Overlay

The "overlay" variant can be used to compare images with a tap/press and hold action or pressing the Enter / Space key when in focus. Its focus-ring offset can be adjusted using the --overlay-focus-offset variable.

Split

"Split" is the simplest of the three variants, as it simply displays both images side by side or one below the other, and does not provide any form of interaction. You can set its columns minimum and maximum width (--split-column-min-width, --split-column-max-width) as well as its column spacing (--split-gap). At least one of the column variables must be a fixed length.

Slots

Slots allow you to define placeholders in your template that can be filled with any markup fragment you want. They are identified using the 'slot' attribute. These placeholder are meant to be used to display the images you want to compare and their associated labels. Pleace add an alt-attribute to describe your images.

Name	Example value
label-before	<label slot="label-before">Original</label>
label-after	<label slot="label-after">After</label>
image-before	<img slot="image-before" src="kasimir.jpg" alt="kasimir" />
image-after	<img slot="image-after" src="kasimir_filter.jpg" alt="kasimir with filter" />

Attributes

Name	Default	Description
variant	slider	Defines the look and behaviour of this component: slider, overlay, split
overlayPrompt	Tap and hold to compare	-
sliderPrompt	Move the slider to compare	-
sliderSteps	5	Number of steps used with Shift + ArrowLeft/ArrowRight
sliderPosition	50	Current slider position expressed in percent

CSS variables

Select and set the following variables to further customize this component

Variable	Purpose	Default value
--base-gap	Spacing for paddings, margins & gaps	16px
--base-radius	Border radius for different elements	8px
variant: slider
--thumb-size	The size of the button which moves the slider	40px
--thumb-border-width	-	3px
--thumb-bar-width	The divider width	--thumb-border-width: 3px
--slider-color	The color for the thumb button and bar	#fff
--slider-color-active	The color for active states	#fff
--label-background-color	-	#fff
--label-color	-	#000
--label-radius	-	--base-radius: 8px
variant: overlay
--overlay-focus-offset	Offset value for focus ring around the image	--base-gap / 2
variant: split
--split-gap	Gap between images	--base-gap: 16px
--split-column-min-width	Min width of a split column	100px
--split-column-max-width	Max width of a split column	1fr

Example usage:

image-comparison {
  --thumb-size: 30px;
}

Custom events

There are two custom events you can listen to:

DragEvent {
  type: 'drag-event',
  targetElement {
    // ...
    sliderPosition: 73,
  }
}

and

PressEvent {
  type: 'press-event',
  targetElement {},
  pressed: true
}

Example usage:

window.addEventListener('press-event', (e) => console.log(e));
// PressEvent {isTrusted: false, pressed: false, targetElement: image-comparison, type: 'press-event', target: Window, …}

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Tooling configs

For most of the tools, the configuration is in the package.json to reduce the amount of files in your project.

If you customize the configuration a lot, you can consider moving them to individual files.

Local Demo with web-dev-server

npm start

To run a local development server that serves the basic demo located in demo/index.html

Inspiration & other useful resources

Some websites I took inspiration from:

• gpucheck.de
• w3schools.com
• mobirise-tutorials.com
• Shoelace a framework agnostic ui library, checkout their own implementation of such a component: Image Comparer

Useful resources:

• "What is Lit?" on the lit.dev site for more information
• Open Web Components