Image
The image plugin adds Notion's image block, a void figure with an editable caption, alt text, width and alignment, embedded from a link, an upload you provide, or a pasted or dropped file. List it to have images.
createImagePlugin() adds Notion’s image block: an “Add an image” panel (your empty snippet, createMediaEmptyPlugin({ empty })) until the block has a source, then the image with an editable caption. Hovering the image, or selecting its block, shows handles to resize it and a toolbar to align it and set its alt text. It is not a default plugin: list createImagePlugin() (or createImagePlugin({ upload })) and the slash menu lists “Image” under Media. Give it an upload, createImagePlugin({ upload }), and the empty block gets an Upload and pasted or dropped image files become image blocks too.
<script lang="ts">
import { Edytor, createImagePlugin } from 'edytor';
// An Upload button next to the link field, and pasted or dropped
// image files uploaded into image blocks.
const image = createImagePlugin({
upload: async (file) => {
const body = new FormData();
body.append('file', file);
const response = await fetch('/api/uploads', { method: 'POST', body });
return (await response.json()).url;
}
});
</script>
<Edytor plugins={[image]} />
The image plugin takes links; given an upload (createImagePlugin({ upload })), files too (Pasted and dropped files). Without one, the view takes no image files: a dropped image goes to the file block when the file plugin uploads, else nowhere. Dropping files on the editor, and the drop line that shows where they land, come with the first media plugin given an upload: with none, a file drop is ignored.
Try it
Hover the picture to align it, resize it or set its alt text; in the empty block, click “Add an image” and upload a file or paste a link. Drag a picture from your desktop over the editor: a line shows where it lands. The editor is local to this page: uploads stay in this tab and a reload resets it.
Customize
The empty block’s panel (empty) and the toolbar over the hovered image (toolbar) are your snippets. Here, a dashed drop zone with a file pill and a link field, and a dark pill with three alignments and an alt field.
<script lang="ts">
import {
Edytor,
createImageToolbarPlugin,
createMediaEmptyPlugin,
type ImageToolbar,
type JSONDoc,
type MediaEmptyController,
type Plugin
} from 'edytor';
// The page's document and the rest of your editor's plugins (the uploads one).
let { value, plugins = [] }: { value?: JSONDoc; plugins?: Plugin[] } = $props();
// The empty slot and the toolbar over the hovered image, drawn below.
const empty = createMediaEmptyPlugin({ empty: emptySlot });
const toolbar = createImageToolbarPlugin({ toolbar: bar });
const aligns = [
{ align: 'left', label: 'Left' },
{ align: 'center', label: 'Center' },
{ align: 'right', label: 'Right' }
] as const;
</script>
<!-- A dashed drop zone: pick a file or paste a link. -->
{#snippet emptySlot(panel: MediaEmptyController)}
{#if panel.pending?.status === 'uploading'}
<!-- The picture at once, from the file in this tab; the bar until it is stored. -->
<div class="zone" role="status">
{#if panel.preview}<img class="preview" src={panel.preview} alt="" />{/if}
<progress value={panel.progress ?? undefined} max="1">Uploading…</progress>
</div>
{:else if panel.readonly}
<div class="zone">No picture yet</div>
{:else}
<div class="zone">
<span class="hint">{panel.icon} Drop a picture, or</span>
{#if panel.canUpload}
<label class="pick">
choose a file
<input
type="file"
accept={panel.accept}
hidden
onchange={(event) => {
const picked = event.currentTarget.files?.[0];
if (picked) void panel.upload(picked);
}}
/>
</label>
{/if}
<input
class="link"
aria-label="Image link"
placeholder="paste a link"
bind:value={panel.draft}
{@attach panel.field}
onkeydown={(event) => event.key === 'Enter' && panel.embed()}
/>
{#if panel.failed}
<small role="alert">That link or file was refused.</small>
{/if}
</div>
{/if}
{/snippet}
<!-- A dark pill: three alignments and a quiet alt text field. -->
{#snippet bar(controls: ImageToolbar)}
{#if controls.box}
{@const box = controls.box}
<div class="pill" {@attach controls.bar}>
{#each aligns as { align, label } (align)}
<button
type="button"
aria-pressed={box.align === align}
onmousedown={(event) => event.preventDefault()}
onclick={() => controls.align(align)}
>
{label}
</button>
{/each}
<button
type="button"
aria-expanded={controls.editing === box.id}
onmousedown={(event) => event.preventDefault()}
onclick={() => controls.toggleAlt()}
>
Alt
</button>
{#if controls.editing === box.id}
<input
class="alt"
aria-label="Alt text"
placeholder="Describe the picture"
value={controls.alt}
oninput={(event) => controls.setAlt(event.currentTarget.value)}
{@attach controls.altField}
/>
{/if}
</div>
{/if}
{/snippet}
<Edytor {value} plugins={[empty, toolbar, ...plugins]} aria-label="Image demo" />
<style>
.zone {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 8px;
padding: 18px 14px;
border: 1.5px dashed #b9b5ad;
border-radius: 12px;
background: #faf8f4;
color: #6b6862;
font-size: 14px;
}
.pick {
padding: 3px 10px;
border-radius: 999px;
background: #355070;
color: #fff;
font-weight: 600;
cursor: pointer;
}
.link {
flex: 1;
min-width: 140px;
padding: 4px 10px;
border: 1px solid #d9d7d2;
border-radius: 999px;
background: #fff;
font: inherit;
outline: none;
}
small {
flex-basis: 100%;
color: #b3402f;
}
.pill {
display: flex;
position: relative;
align-items: center;
gap: 2px;
width: max-content;
margin-left: auto;
padding: 3px;
border-radius: 999px;
background: #1f2328;
box-shadow: 0 8px 20px rgb(0 0 0 / 0.25);
}
.pill button {
padding: 2px 10px;
border: 0;
border-radius: 999px;
background: transparent;
color: #c9d1d9;
font: 600 12px/20px ui-sans-serif, system-ui, sans-serif;
cursor: pointer;
}
.pill button:hover {
color: #fff;
}
.pill button[aria-pressed='true'],
.pill button[aria-expanded='true'] {
background: #2f81f7;
color: #fff;
}
.alt {
position: absolute;
top: 36px;
right: 0;
width: 220px;
padding: 6px 10px;
border: 0;
border-radius: 10px;
background: #1f2328;
color: #e6edf3;
font: 13px/1.4 ui-sans-serif, system-ui, sans-serif;
outline: none;
}
.preview {
max-width: 100%;
border-radius: 4px;
}
</style>
Options
createImagePlugin(options) takes an ImagePluginOptions: upload, an Uploader ((file, report) => Promise<string>) that stores a file and answers its URL; without it the plugin takes links only. Its chrome’s parts that draw your markup are their own plugins: the empty block’s panel (createMediaEmptyPlugin({ empty })), the toolbar over the hovered image (createImageToolbarPlugin({ toolbar }): the alignment buttons and the alt field at its top right, their behavior {@attach toolbar.bar} and {@attach toolbar.altField}; without it, the resize handles alone) See Menus and handles.
The kind
| Kind | Element | Data (ImageData) |
Preset |
|---|---|---|---|
image |
figure |
{ src?: string, alt?: string, width?: number, align?: ImageAlign } |
Image (🖼, group Media, keywords picture, photo, img) |
| Key | Meaning |
|---|---|
src |
The image’s source (see below). Without one the block shows the “Add an image” panel. |
alt |
The image’s text alternative, rendered as its alt. None renders alt="" (a decorative image). |
width |
Its width in CSS pixels, never more than its block (max-width: 100%). None: its natural width. |
align |
'left', 'center' (the default) or 'right': where an image narrower than its block sits. Any other value reads as 'center'. |
The block is void: it is not part of the text flow, takes no children and is never merged. Its only text is the caption, which stays editable. A click on the picture selects the block, as in Notion (its toolbar shows, Delete removes it, see presses on chrome); a click in the caption puts the caret there, at the click. The command id is block.image. The kind declares no empty shape, so turning a paragraph into an image keeps the paragraph’s text as the caption.
A source is accepted only when it is an http: or https: URL, a blob: URL or an inline data:image/… URL. Any other value, in the document or typed in the panel, is treated as no source. The check is exported as safeImageSrc(value) (the accepted source, or null), and the types ImageData and ImageAlign and the constant MIN_IMAGE_WIDTH are exported too. A failed upload shows the panel’s error instead of an image.
An inline image is stored in the document itself, and every catch-up and every update that carries the block sends it again, so the plugin takes one only up to MAX_INLINE_IMAGE_BYTES (1 MiB of its data: URL). Give the plugin an upload that stores the file and answers its URL: that is the way to add a large image.
- A larger one pasted in the link field is refused with a message that points to the Upload button (or, without
upload, to hosting the file and pasting its link), and an HTML paste does not import it. A document that already holds a larger one still shows it. storableImageSrc(value)is the check the writes use (safeImageSrc, but no inline image over the cap).
Empty block
Without a source, the block shows an “Add an image” button. Clicking it opens a panel with:
- a link field (“Paste the image link…”); Enter or the “Embed image” button sets
data.src; - an “Upload” button, only with the plugin’s
upload. It opens a file picker for images, callsupload(file)and embeds the URL it answers; - a short error line when the link is not an accepted source.
In a readonly view the block shows a passive placeholder instead, with no button, link field or file picker, so a viewer can never start upload. In an editable view the write is a src data write (patchData), one undo step.
Pasting and dropping files
With the plugin’s upload, the view claims a paste or a drop that carries image files (an image/* type), as Notion does:
- Each file becomes an empty image block. A pasted one goes where a pasted image goes (after the caret’s line, the text after the caret moving to a new line, as for an HTML image). A dropped one goes where the drop indicator shows while you drag it over the editor: the same line a block drag draws, between blocks, inside one or beside one, as Notion does (Pasted and dropped files); it never replaces a block selection. All the files of one paste or drop are one command and one undo step.
- While its file uploads, your
emptysnippet shows it: the picture shows at once: the controller’spreviewis a localblob:URL of the file (never stored, revoked once the upload ends) and itsprogressfills asupload(file, report)callsreport.progress(fraction)(nullwithout it), as for a media block (pendingis{ status: 'uploading', preview, name, size, progress }); the demo shows the picture with a bar. Without the media empty plugin, the block’s own markup shows the picture and the bar ([data-edytor-upload]). This is this view’s state only: a peer sees the empty image block until the URL arrives. - When
upload(file)answers, its URL fills the block’ssrc. That write is kept out of the history (dispatcher.outside, see History), so the paste stays the one step: undo removes the image, URL included, and redo brings it back whole. When the upload ends while the image is not shown (its paste undone, the block deleted), this view keeps the URL and fills the block when it shows again (a redo, an undo of the delete), still outside the history. A block that never comes back gets nothing. - A failed upload, or an answer that is not an accepted source, leaves the block empty, its panel open with “The upload failed: try again or paste a link.” Embedding a link or an upload from that panel clears the error.
A paste whose HTML shows text (an office app also puts a picture of the copied text on the clipboard) is imported as HTML instead. A file that is no image goes to the video, audio or file kind listed, in the same paste (Pasted and dropped files); one no kind takes is left to your own onPaste hook (unclaimed, it inserts nothing). A readonly view ignores the paste.
Resize, alignment and alt text
Hovering an image in an editable view shows, in the editor’s overlay (never inside the editable host), the chrome below. With no image under the pointer, an image block that is the whole block selection (clicked, or selected from the keyboard) shows it too, so its alignment and alt text are reachable without hovering.
- A resize handle on each side, a pill at mid-height. Dragging one resizes the image live; the release writes
data.width(whole pixels, one undo step). A centered image grows on both sides, so it changes by twice the pointer’s move; a left- or right-aligned one changes by the move. The width stays betweenMIN_IMAGE_WIDTH(48 px) and the block’s width. While you drag, only your view shows the new width (no peer gets a frame); Escape drops the drag and writes nothing, and the editor takes the keys after the release, so Mod+Z undoes it at once. - A toolbar at the image’s top right: Align left, Align center and Align right (each sets
data.align, one undo step) and Alt text, which opens a field under it. Typing there writesdata.altas you type; the keystrokes group into one undo step, as in a field bound toblock.data(a replaced value, or a pause past the history’s capture window, starts a new one). Enter or Escape closes it and gives the keys back to the editor; a press outside the field and the toolbar, or focus moving elsewhere, closes it too, and the chrome follows the pointer again.
A readonly view shows none of this, and a drag in progress ends when the view turns readonly.
Image and caption
With a source, the block renders the image (its alt, its width, not draggable) in a wrapper that places it by align, then the caption in a <figcaption>. With richTextPlaceholder, an empty caption shows “Write a caption…” while focused.
To set the source from code:
block.data.src = 'https://example.com/photo.jpg';
block.data.alt = 'A red barn';
block.data.width = 320;
block.data.align = 'left';
The writes of one task are one patchData: one command and one undo step, however many properties they write.
Clipboard
- Copying exports
<figure><img src="…" alt="…" width="…"><figcaption>caption</figcaption></figure>(noimgwithout a source, nowidthwithout one), withdata-align="left"or"right"on thefigurewhen the image is not centered. - Pasting HTML imports a
figurethat contains animgwith an acceptedsrc, and a bareimgwith one, as an image block: its source, itsalt, itswidthattribute (when a positive number) and the figure’sdata-align. Animginside a paragraph splits it around the image (HTML import).
Styling
The Notion theme styles the block. Without it, target:
| Selector | Matches |
|---|---|
[data-edytor-type='image'] |
The figure |
[data-edytor-image] |
The wrapper around the img (data-align) |
[data-edytor-image-empty] |
Where the empty state (your empty snippet) renders |
[data-edytor-image-resize] |
A resize handle in the overlay (="left", ="right"; data-dragging="true" while it drags); its ::after is the pill |
[data-edytor-image-toolbar-slot] |
Where your toolbar renders, at the image’s top right |
[data-edytor-image-toolbar] |
Your toolbar’s bar (toolbar.bar marks it) |
[data-edytor-image-alt] |
Your alt text field (controls.altField marks it) |
The plugin places the resize handles and their pills; the Notion theme paints the pills (a dark pill with a light ring, --edytor-image-handle-color), and without it they are unpainted. An empty failure is "invalid", "upload" for a failed upload, or "inline" for an inline image over 1 MiB.
To change the markup, list a plugin that names the image kind’s snippet (see Restyling a kind) before createImagePlugin(...): the image plugin’s other fields stay. To replace the kind itself, define every field you need in your own plugin: definitions are first-wins, field by field.
Placement. The package places no popup: your markup places itself by the image toolbar’s toolbar.anchor (the image: its top right), a virtual element read live. With Floating UI, computePosition(anchor, element, { strategy: 'fixed', middleware: [offset(8), flip(), shift({ padding: 8 })] }) under autoUpdate; with bits-ui, customAnchor={anchor}. See Menus and handles.