<image-comparison>

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

https://user-images.githubusercontent.com/1145514/189548478-f2fc7f66-e886-4d61-93e5-7e0281d32b17.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