useImage

The useImage hook makes it easy to implement inline images into your rich text editor.

The DOM already supports inline images with a one-liner: document.execCommand('insertImage', null, 'https://mycdn.com/path-to-image.png'). Unfortunately, though, it still can be hard to choose an image, create a url for the image, style the image, or remove an image. Which is where the useImage hook helps out.

Basic Example

import {useImage} from 'bandicoot'

function Image() {
  const {chooseFile} = useImage()

  return (
    <button onClick={chooseFile}>
      Insert Image from Computer
    </button>
  )
}

Advanced Example

import {useImage} from 'bandicoot'

function RemovableImage() {
  const {chooseFile, removeImage} = useImage({processImgElement, fileBlobToUrl, acceptImgTypes: '.png'})

  return (
    <button onClick={chooseFile}>
      Insert Image from File
    </button>
  )

  function processImgElement(imgElement) {
    // Every time an image gets inserted, this function gets called with the DOM img element
    imgElement.addEventListener('click', () => {
      if (window.prompt('Are you sure you want to remove this image?')) {
        removeImage(imgElement)
      }
    })
  }

  function fileBlobToUrl(fileBlob) {
    const formData = new FormData()
    formData.append('files', fileBlob)

    // We need to return a promise that resolves with a string url that the <img> element can use.
    return fetch('/server-api-that-handles-file-uploads', {
      method: 'POST',
      body: formData,
    })
    .then(response => response.json())
    .then(json => json.newlyCreatedFileUrl)
  }
}

API

const {chooseFile, removeImage} = useImage({processImgElement, fileBlobToUrl, acceptImgTypes})

Arguments

useImage can be called with no arguments (to use the defaults) or with a single object argument with the following properties:

processImgElement (optional): A function that will be called with each <img> dom element in the rich text editor. This can be used to set up click listeners, change the style, etc. The function will be called for img elements in the initialHTML, calls to setHTML, and also for every img element that is inserted via useImage(). Defaults to a no-op function.
fileBlobToUrl (optional): A function that will be called whenever the user has picked a file from their computer to insert into the rich text editor. The fileBlobToUrl function will be called with one argument, a File. The return value of fileBlobToUrl must be a promise that resolves with a string url for that FileBlog object. This is useful for uploading a file to a server before inserting it into the DOM. Defaults to calling URL.createObjectURL(file). If not provided, bandicoot will use data urls for storing images.
acceptImgTypes (optional): A comma delimited string that configures what file types the file input should accept. Default is '.jpg, .png, image/*'.

Return value

useImage returns an object with the following properties:

chooseFile(): A function that will open up a file picker and allow the user to choose a file from their computer. When the user selects an image, that image will be inserted into the RichTextEditor.
removeImage(imgElement): A function that will remove an image from the rich text editor while preserving undo/redo state. This function must be called with one argument, the <img> dom element that you wish to remove.

Notes

useImage uses useDocumentExecCommand underneath the hood to call document.execCommand().

Inserting images