API Documentation

Complete reference for the <image-editor> component

Attributes

Configure the component behavior using these HTML attributes.

Attribute Type Default Description
src string — URL of image to load on initialization.
mode 'light' | 'dark' auto Theme mode. When omitted, auto-detects page-level dark mode signals (body.dark, data-theme, data-bs-theme, data-mode, color-scheme).
width number — Constrain editor width in pixels.
height number — Constrain editor height in pixels.
format 'png' | 'jpeg' | 'webp' 'png' Default export format.
quality number (0–1) 0.92 Export quality for JPEG/WebP formats.
max-history number 50 Maximum undo steps to keep in history.
readonly boolean false Disable all editing operations. Image can still be viewed with zoom/pan.
no-toolbar boolean false Hide the toolbar for programmatic/API-only usage.
aspect-ratio string — Lock crop to a specific ratio (e.g. '16:9', '4:3', '1:1').

Attribute Examples

<!-- Basic usage --> <image-editor></image-editor> <!-- Pre-load an image --> <image-editor src="photo.jpg"></image-editor> <!-- Dark mode with JPEG export --> <image-editor mode="dark" format="jpeg" quality="0.85"></image-editor> <!-- Read-only with constrained size --> <image-editor readonly width="600" height="400"></image-editor> <!-- Locked 16:9 crop ratio --> <image-editor aspect-ratio="16:9"></image-editor> <!-- API-driven (no toolbar) --> <image-editor no-toolbar></image-editor>

Properties (read-only)

Access the current state of the editor through these properties.

Property Type Description
imageWidth number Current image pixel width
imageHeight number Current image pixel height
hasImage boolean Whether an image is loaded
isDirty boolean Whether edits have been made since load
canUndo boolean Whether undo is available
canRedo boolean Whether redo is available
zoomLevel number Current zoom level (1 = 100%)
currentTool string | null Active tool name or null
historyLength number Number of entries in the history stack

Methods

Control the editor programmatically.

Method Returns Description
loadImage(src) Promise<void> Load image from URL, File, or Blob
crop(x, y, w, h) void Crop to specified pixel region
rotate(degrees) void Rotate by 90° increments
flipHorizontal() void Flip horizontally
flipVertical() void Flip vertically
resize(w, h) void Resize to specified dimensions
applyFilter(name, value) void Set a filter value (e.g. 'brightness', 1.2)
resetFilters() void Reset all filters to defaults
undo() void Undo last operation
redo() void Redo last undone operation
reset() void Reset to original loaded image
zoomTo(level) void Set zoom level (1 = 100%)
zoomToFit() void Fit image to workspace
getBlob(format?, quality?) Promise<Blob> Get the current image as a Blob
getDataURL(format?, quality?) string Get the current image as a data URL
download(filename?, format?, quality?) void Trigger a browser download of the image

Methods Example

const editor = document.querySelector('image-editor') // Load and process an image await editor.loadImage('photo.jpg') editor.rotate(90) editor.applyFilter('brightness', 1.2) editor.applyFilter('contrast', 1.1) editor.resize(800, 600) // Export const blob = await editor.getBlob('webp', 0.9) editor.download('edited-photo.webp', 'webp', 0.9)

Events

Listen for editor state changes using custom events.

Event Detail Fires when
image-load { width, height, src } Image loaded successfully
image-load-error { src, error } Image failed to load
image-edit { action, params } Any edit applied (crop, rotate, filter, etc.)
image-export { format, quality, size } Image exported or downloaded
tool-change { tool, previous } Active tool changed
zoom-change { level } Zoom level changed
history-change { canUndo, canRedo, length } History stack changed

Events Example

const editor = document.querySelector('image-editor') editor.addEventListener('image-load', (e) => { console.log(`Loaded ${e.detail.width}x${e.detail.height} image`) }) editor.addEventListener('image-edit', (e) => { console.log(`Edit: ${e.detail.action}`, e.detail.params) }) editor.addEventListener('image-export', (e) => { console.log(`Exported ${e.detail.format} (${e.detail.size} bytes)`) })

Slots

Use the default slot to customize the drop zone content shown before an image is loaded.

Slot Description
(default) Custom content for the drop zone area. Replaced once an image is loaded.

Slot Example

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

CSS Custom Properties

Customize the appearance using CSS custom properties. Set these on the image-editor element or a parent container.

Property Default Description
--image-editor-bg #ffffff Editor background
--image-editor-border-color #d1d5da Border color
--image-editor-border-radius 8px Corner radius
--image-editor-font-family system-ui UI font family
--image-editor-text-color #24292e Text color
--image-editor-text-muted #586069 Muted text color
--image-editor-margin 1rem 0 Outer margin
--image-editor-toolbar-bg #f6f8fa Toolbar background
--image-editor-toolbar-border #d1d5da Toolbar border
--image-editor-toolbar-padding 4px 8px Toolbar padding
--image-editor-button-bg transparent Button background
--image-editor-button-color #586069 Button icon/text color
--image-editor-button-hover-bg #f3f4f6 Button hover background
--image-editor-button-active-bg #e5e7eb Active button background
--image-editor-button-active-color #2563eb Active button color
--image-editor-button-radius 4px Button corner radius
--image-editor-button-disabled-opacity 0.4 Disabled button opacity
--image-editor-workspace-bg #e5e5e5 Workspace/canvas background
--image-editor-workspace-check-color #cccccc Transparency checkerboard color
--image-editor-context-bg #f6f8fa Context bar background
--image-editor-context-border #d1d5da Context bar border
--image-editor-accent-color #2563eb Accent/primary color
--image-editor-focus-color #2563eb Focus ring color
--image-editor-crop-border #2563eb Crop selection border
--image-editor-crop-handle-color #2563eb Crop handle color
--image-editor-crop-overlay rgba(0,0,0,0.5) Crop dim overlay
--image-editor-crop-grid-color rgba(255,255,255,0.3) Crop grid line color
--image-editor-status-bg #f6f8fa Status bar background
--image-editor-status-color #586069 Status bar text color
--image-editor-status-font-size 0.75rem Status bar font size
--image-editor-slider-track #d1d5da Slider track color
--image-editor-slider-thumb #2563eb Slider thumb color

Theming Example

/* Custom purple theme */ image-editor.purple { --image-editor-accent-color: #8b5cf6; --image-editor-toolbar-bg: #faf5ff; --image-editor-border-color: #c4b5fd; --image-editor-button-active-color: #8b5cf6; } /* Custom dark theme override */ image-editor.custom-dark { --image-editor-bg: #1a1a2e; --image-editor-toolbar-bg: #16213e; --image-editor-workspace-bg: #0f0f1a; --image-editor-text-color: #eee; --image-editor-border-color: #0f3460; }

Filter Names

Available filter names for use with applyFilter(name, value).

Name Range Default Description
brightness 0.5 – 2 1 Image brightness
contrast 0.5 – 2 1 Image contrast
saturate 0 – 3 1 Color saturation
blur 0 – 10px 0 Gaussian blur
grayscale 0 – 100% 0 Grayscale conversion
sepia 0 – 100% 0 Sepia tone

Keyboard Shortcuts

The component supports keyboard navigation for accessibility.

Key Action
Tab Navigate between toolbar buttons
Enter / Space Activate focused button
Escape Cancel active tool or close panel

Browser Support

Works in all modern browsers that support Web Components and Canvas 2D:

Accessibility

The component is built with accessibility in mind: