<image-editor>

A basic image editor web component for cropping, rotating, filtering, resizing, and exporting images. Built with vanilla JavaScript, zero dependencies, and designed for content editing workflows.

Demos · API Reference

Features

Feature	Description
Crop	Draggable handles with rule-of-thirds grid and aspect ratio presets
Rotate	90° left/right rotation
Flip	Horizontal and vertical flip
Resize	Aspect ratio lock with common size presets
Filters	Brightness, contrast, saturation, blur, grayscale, sepia
Undo/Redo	Configurable history depth
Export	PNG, JPEG, or WebP with quality control
Zoom/Pan	Scroll wheel zoom, click-and-drag pan
Themes	Light/dark mode with auto-detection
Drag & Drop	Drop images directly onto the editor
Accessible	Full keyboard navigation, ARIA labels
Themeable	35+ CSS custom properties

Installation

npm install @profpowell/image-editor

Or include directly via CDN:

<script type="module" src="https://unpkg.com/@profpowell/image-editor"></script>

Usage

Basic

<script type="module">
  import '@profpowell/image-editor'
</script>

<image-editor></image-editor>

With a pre-loaded image

<image-editor src="photo.jpg"></image-editor>

Dark mode with JPEG export

<image-editor mode="dark" format="jpeg" quality="0.85"></image-editor>

Constrained size

<image-editor width="600" height="400"></image-editor>

Custom drop zone message

<image-editor>
  <p>Drag your photo here to start editing</p>
</image-editor>

Programmatic usage

const editor = document.querySelector('image-editor')

// Load from file input
fileInput.addEventListener('change', (e) => {
  editor.loadImage(e.target.files[0])
})

// Listen for edits
editor.addEventListener('image-edit', (e) => {
  console.log('Edit:', e.detail.action)
})

// Export
const blob = await editor.getBlob('webp', 0.9)

Attributes

Attribute	Type	Default	Description
src	string	—	URL of image to load
mode	'light' | 'dark'	auto	Theme mode
width	number	—	Editor width in px
height	number	—	Editor height in px
format	'png' | 'jpeg' | 'webp'	'png'	Default export format
quality	number (0–1)	0.92	JPEG/WebP export quality
max-history	number	50	Maximum undo steps
readonly	boolean	false	Disable editing
no-toolbar	boolean	false	Hide toolbar
aspect-ratio	string	—	Lock crop ratio (e.g. '16:9')

Methods

Method	Returns	Description
loadImage(src)	Promise<void>	Load from URL, File, or Blob
crop(x, y, w, h)	void	Crop to pixel region
rotate(degrees)	void	Rotate by 90° increments
flipHorizontal()	void	Flip horizontally
flipVertical()	void	Flip vertically
resize(w, h)	void	Resize to dimensions
applyFilter(name, value)	void	Apply filter
resetFilters()	void	Reset all filters
undo() / redo()	void	History navigation
reset()	void	Reset to original image
zoomTo(level)	void	Set zoom (1 = 100%)
zoomToFit()	void	Fit image to view
getBlob(format?, quality?)	Promise<Blob>	Get as Blob
getDataURL(format?, quality?)	string	Get as data URL
download(filename?, format?, quality?)	void	Browser download

Events

Event	Detail	When
image-load	{ width, height, src }	Image loaded
image-load-error	{ src, error }	Load failed
image-edit	{ action, params }	Edit applied
image-export	{ format, quality, size }	Exported
tool-change	{ tool, previous }	Tool changed
zoom-change	{ level }	Zoom changed
history-change	{ canUndo, canRedo, length }	History changed

CSS Custom Properties

All styling is controlled via CSS custom properties prefixed with --image-editor-*:

image-editor {
  --image-editor-accent-color: #8b5cf6;
  --image-editor-toolbar-bg: #faf5ff;
  --image-editor-border-color: #c4b5fd;
}

See the full list in the API reference.

Vanilla Breeze

This component is Vanilla Breeze compatible — all tokens map automatically when used on a VB-themed page.

Filter Names

Name	Range	Default	Description
brightness	0.5–2	1	Brightness
contrast	0.5–2	1	Contrast
saturate	0–3	1	Saturation
blur	0–10px	0	Gaussian blur
grayscale	0–100%	0	Grayscale
sepia	0–100%	0	Sepia tone

Keyboard Shortcuts

Key	Action
Ctrl/Cmd + Z	Undo
Ctrl/Cmd + Shift + Z	Redo
Escape	Cancel current tool
Enter	Apply crop
Arrow keys	Nudge crop selection
Shift + Arrow	Nudge crop by 10px

Browser Support

Requires browsers with support for:

• Custom Elements v1
• Shadow DOM v1
• Canvas 2D API
• CSS Custom Properties

Development

npm install
npm run dev        # Start dev server
npm test           # Run Playwright tests
npm run test:ui    # Interactive test UI
npm run build      # Production build
npm run lint       # Lint
npm run format     # Format

License

MIT