Image

Type: Node · Category: Rich Content

Image embeds an image block into the document. Renders as a wrapper <div> container around an <img> tag in HTML output for responsive alignment and scaling.

Demo

Installation

import { Image } from "@arkpad/extension-image";

Commands

The extension registers two commands for inserting and modifying image blocks:

// Inserts a new image block at the current selection
editor.runCommand("setImage", {
  src: "https://example.com/photo.jpg",
  alt: "An aesthetic landscape backdrop",
  title: "Nature Landscape",
  width: "80%",
  align: "center", // Options: 'left' | 'center' | 'right'
});

// Updates attributes of the currently selected image (requires image selection)
editor.runCommand("updateImage", {
  width: "50%",
  align: "left",
});

Chaining Commands

You can chain commands to insert an image and focus the editor:

editor.chain().focus().setImage({ src: "https://example.com/photo.jpg" }).run();

Attributes

Name	Type	Default	Description
`src`	`string`	`null`	The URL source of the image (required).
`alt`	`string`	`null`	Alternate text description for accessibility.
`title`	`string`	`null`	Mouse hover tooltip title.
`width`	`string`	`"100%"`	The width of the image wrapper (e.g. `50%`, `300px`, `100vw`).
`align`	`string`	`"center"`	Horizontal alignment of the image block (`left`, `center`, or `right`).

Active State

const isActive = editor.isActive("image");

Configuration

Options

Name	Type	Default	Description
`HTMLAttributes`	`Record<string, any>`	`{}`	Key-value pairs of attributes to render directly on the inner `<img>` DOM element.

Image.configure({
  HTMLAttributes: {
    loading: "lazy",
    class: "arkpad-rendered-image",
  },
});

Advanced Interactive UX

Arkpad's image extension includes a fully custom, touch-enabled interactive node view that displays rich scaling and styling controls on selection:

Interactive Resizing

Aspect Ratio Lock: Drag handles appear on the corners of the image on selection, allowing smooth, fluid width resizing.
Symmetric Centered Scaling: When the image is center-aligned, resizing coordinates scale symmetrically from both sides.
Real-time Percentage Tooltip: Shows the current percentage width (e.g. 65%) in a dark floating tooltip overlay as you drag.
Mobile Touch Support: Binds touch gestures (touchstart/touchmove/touchend) for high-fidelity resizing on phones and tablets.
Tailwind Margin Collapse: Auto-collapses default typography margins on selection, pulling resizing corners flush with the image boundaries.

A floating popover toolbar appears centered directly above the selected image for quick attribute manipulation:

Alignment Controls: Quick left, center, and right alignments.
Alt Text Setter: Opens an interactive prompt to write custom Alt / Caption text.
Instant Deletion: Single-click deletion with a red-accented trash button.

Image

On this page