Consider an equipment manual with two photographs: a connector close-up and the whole instrument. Uploading the close-up should add that image at the intended location without replacing the instrument photograph. The resulting document must still load the image when another authorized reader opens the manual.
Define the upload result before wiring the button
Decide what your existing media service returns on success. A durable HTTPS image URL is different from a browser blob: URL used for a temporary local preview. A data URL embeds image bytes in the document; it does not demonstrate that a media file reached your server.
The upload endpoint must enforce the application's authentication, authorization, file-size, and actual file-content rules. An input's accept="image/*" helps the file chooser but does not perform server validation. Keep failed uploads out of the document and give the author a visible error with a retry route.
If image URLs require reader authentication or expire, test that access model with the intended manual reader. A link that works only in the uploader's current session is unsuitable for a published manual.
Insert a completed upload through Quill's API
In a Quill 2 application that already has the image format enabled, this bounded helper inserts an uploaded URL at the current selection:
function insertUploadedImage(quill, returnedUrl, mediaOrigin) {
const url = new URL(returnedUrl);
if (url.protocol !== 'https:' || url.origin !== mediaOrigin) {
throw new Error('Unexpected media URL');
}
const range = quill.getSelection(true);
const index = range ? range.index : quill.getLength() - 1;
quill.insertEmbed(index, 'image', url.href, 'user');
quill.setSelection(index + 1, 0, 'api');
}
mediaOrigin is your trusted configured origin, such as the actual HTTPS media host your service uses. It is not a value supplied by the uploaded file. This narrow URL check does not verify file contents, image ownership, or access permissions.
Call the helper only after a successful upload. This example deliberately uses the selection current at insertion time. If your product promises placement where the author originally clicked Image, preserve that position through intervening document edits or hold editing while the upload is pending. A saved numeric index alone can point somewhere else after text is inserted or deleted.
The API call inserts the embed; it does not replace an active text selection. If replacing selected content is your intended behavior, implement and test that policy explicitly rather than silently deleting text during an image upload.
Connect one custom image action
For an already initialized editor, obtain its toolbar and replace the image handler:
const toolbar = quill.getModule('toolbar');
toolbar.addHandler('image', () => {
// Open your existing accessible upload dialog.
// On success, call insertUploadedImage with its returned URL.
});
This fragment shows the toolbar connection. It intentionally relies on your application's real dialog and upload implementation; it is not a complete uploader. Cancellation should leave the document unchanged. If the author switches manuals before an upload finishes, reject that stale completion instead of inserting into the newly opened record.
Check the image and the document separately
For the connector photograph, inspect the upload response, the inserted embed, and the saved document. Quill's Delta format represents an image as an embed value. quill.getContents() retrieves that formatted document; your save action must persist it through the application's existing route.
Test a successful upload, a canceled chooser, and a rejected file. On success, reopen the saved manual and confirm the close-up remains next to its connector instruction while the whole-instrument photograph remains unchanged. Check the image at a narrow reader width too.
The Quill HTML import guide covers loading existing document content. An uploaded image introduces a separate media record and access lifetime. Keep the original photograph until both the stored manual and its reader can load the intended derivative.