A small React hook to turn elements into fully renderable & editable content surfaces, like code editors, using contenteditable (and magic)
npm install use-editableA small React hook to turn elements into fully renderable & editable content surfaces, like code editors, using contenteditable (and magic)
useEditable is a small hook that enables elements to be contenteditable while still being fully renderable. This is ideal for creating small code editors or prose textareas in just 2kB!
It aims to allow any element to be editable while still being able to render normal React elements to it — no innerHTML and having to deal with operating with or rendering to raw HTML, or starting a full editor project from scratch.
Check out the full demo on CodeSandbox with prism-react-renderer!
First install use-editable alongside react:
``sh`
yarn add use-editableor
npm install --save use-editable
You'll then be able to import useEditable and pass it an HTMLElement ref and an onChange handler.
`js
import React, { useState, useRef } from 'react';
import { useEditable } from 'use-editable';
const RainbowCode = () => {
const [code, setCode] = useState('function test() {}\nconsole.log("hello");');
const editorRef = useRef(null);
useEditable(editorRef, setCode);
return (
}}>
{content}
And just like that we've hooked up
useEditable to our editorRef, which points to the setCode
element that is being rendered, and towhich drives our state containing some code.MutationObserverBrowser Compatibility
This library has been tested against and should work properly using:
- Chrome
- Safari
- iOS Safari
- FirefoxThere are known issues in IE 11 due to the
method being unable tocontenteditable
read text nodes that have been removed via the.contenteditableFAQ
$3
Traditionally, there have been three options when choosing editing surfaces in React. Either one
could go for a large project like ProseMirror / CodeMirror or similar which take control over much
of the editing and rendering events and are hence rather opinionated, or it's possible to just
useand render to raw HTML that is replaced in the element's content, or lastly onetextarea
could combine awith an overlappingdivthat renders stylised content.contenteditableAll three options don't allow much customisation in terms of what actually gets rendered or put
unreasonable restrictions on how easy it is to render and manage an editable's content.So what makes rendering to a
element so hard?use-editableTypically this is tough because they edit the DOM directly. This causes most rendering libraries, like
React and Preact to be confused, since their underlying Virtual DOMs don't match up with the actual
DOM structure anymore. To prevent this issuecreates aMutationObserver, which watchescontenteditable
over all changes that are made to theelement. Before it reports these changes tocontenteditable
React it first rolls back all changes to the DOM so that React sees what it expects.Furthermore it also preserves the current position of the caret, the selection, and restores it once
React has updated the DOM itself. This is a rather common technique foreditors, butMutationObserver
theaddition is what enablesuse-editableto let another view library update the element'scontenteditable
content.$3
Currently either the rendered elements' text content has to eventually exactly match the code input,
or your implementation must be able to convert the rendered text content back into what you're using
as state. This is a limitation of how's work, since they'll only capture the actualuse-editable
DOM content. Sincedoesn't aim to be a full component that manages the render cycle, itonChange
doesn't have to keep any extra state, but will only pass the DOM's text back to thecallback.onChangeUsing the
callback you'll also receive aPositionobject describing the cursor position,update
the current line number, and the line's contents up until the cursor, which is useful for auto-suggestions,
which could then be applied with thefunction thatuseEditablereturns to update the cursorelementRef
position.API
$3
The first argument is
and accepts a ref object of typeRefObjectwhichnull
points to the element that should become editable. This ref is allowed to beor change duringonChange
the runtime of the hook. As long as the changes of the ref are triggered by React, everything should
behave as expected.The second argument is
and accepts a callback of type(text: string, pos: Position) => voidcontenteditable
that's called whenever the content of thechanges. This needs to be set up so thattext
it'll trigger a rerender of the element's contents.The
thatonChangereceives is just the textual representation of the element's contents, while thePositionit receives contains the current position of the cursor, the line number (zero-indexed), andoptions
the content of the current line up until the cursor, which is useful for autosuggestions.The third argument is an optional
object. This accepts currently two options to changedisabled
the editing behavior of the hook:- The
option disables editing on the editable by removing thecontentEditableattribute fromindentation
it again.
- Theoption may be a number of displayed spaces for indentation. This also enables theTab
improvedkey behavior, which will indent the current line or dedent the current line when shift isoptions.indentation
held (Be aware that this will make the editor act as a focus trap!)When
is set thenuseEditablewill prevent the insertion of tab characters anduseEditable
will instead insert the specified amount of whitespaces, which makes handling of columns much easier.Additionally the
hook returns anEdithandle with several methods, as documented below.Edit.update(content: string): void#### Edit.update
Edit.insert(append: string, offset?: number): voidReplaces the entire content of the editable while adjusting the caret position.
This will shift the caret by the difference in length between the current content and the passed content.#### Edit.insert
offsetInserts new text at the caret position while deleting text in range of the offset (which accepts negative offsets).
For example, whenis set to-1then a single character is deleted to the left of the caret before2
inserting any new text. When it's set tothen two characters to the right of the carets are deleted.append
Thetext may also be set to an empty string to only apply deletions without inserting any text.offset
When any text is selected then it's simply erased first andis ignored.Edit.move(pos: number | { row: number; column: number }): void#### Edit.move
numberThis moves the caret to the specified position. The position may either be a character index (a
)row
or coordinates specifying aandcolumnseparately.Edit.getState(): { text: string; position: Position }#### Edit.getState
onChangeThis method allows getting the current state of the editable, which is the same as what
usuallyonChange
receives. This is useful when adding custom editing actions in a key down handler or when programmatically
imitatingotherwise, while the editable is selected.react-liveAcknowledgments
, which I've worked oncontenteditable
had one of the early tinyeditors. (But with raw HTML updates)react-simple-code-editor
-was the first (?) library to use a split textareacodejar
and rendering surface implementation, which presented what a nice editing API should look like.
-contains the best tricks to manage selections, although it lacks somecodemirror.next` is an invaluable source to see different techniques when
Firefox workarounds. It also uses raw HTML highlighting / updating.
-
handling text input and DOM update tricks.