image-comparison-component
TypeScript icon, indicating that this package has built-in type declarations

0.0.5 • Public • Published

<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

slider variant

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

overlay variant

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

side by side split view variant

"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:

Useful resources:

Package Sidebar

Install

npm i image-comparison-component

Weekly Downloads

1

Version

0.0.5

License

MIT

Unpacked Size

106 kB

Total Files

30

Last publish

Collaborators

  • tonyspegel