TipTap Image Extension (@explita/tiptap-extension-image) is a framework-agnostic, enhanced replacement for the default TipTap image extension built for TipTap v3 and ProseMirror. Standard editor image extensions assume image URLs already exist, forcing developers to build custom upload placeholders, drag-and-drop listeners, progress states, and error handling from scratch. This extension solves that by delivering a complete, self-contained node view that manages the full image lifecycle directly inside the editor document.
The extension introduces interactive upload placeholders featuring dashed drop zones, click-to-upload file selectors, drag-and-drop uploads, and automatic clipboard paste handling (pasteImages: true). When files are dropped or pasted, an animated progress indicator displays at the cursor position. The onUpload callback receives File[] and returns structured ImageAsset metadata, supporting single files or multi-image batch insertions. If an upload fails or file types are rejected, inline error states with descriptive messages render directly within the node view without breaking editor document flow.
Once inserted, images feature a floating alignment toolbar supporting inline, left, center, right, and reset options (setImageAlignment). For dimensional adjustments, the built-in drag-resize engine (resize: { enabled: true, directions, minWidth, minHeight, preserveAspectRatio }) enables users to resize images interactively from corners (se, ne, nw, sw) or edges (e, w, n, s) with automatic aspect-ratio locking.
Built with zero dependencies on React, Vue, or Tailwind CSS, the extension runs on pure DOM node views and works seamlessly across any frontend stack. It integrates with external media pickers via onPick (connecting to Cloudinary, AWS S3, or custom asset galleries) and supports programmatic URL insertion via setExternalImage. All styling is self-contained via inline CSS and CSS custom properties (--image-ph-bg, --image-toolbar-bg), enabling effortless dark mode adapting and deep styling customization via HTMLAttributes and [data-image-node] selectors.