All Projects → kitten → Use Editable

kitten / Use Editable

Licence: mit
A small React hook to turn elements into fully renderable & editable content surfaces, like code editors, using contenteditable (and magic)

Programming Languages

typescript
32286 projects

Projects that are alternatives of or similar to Use Editable

Edwood
Go version of Plan9 Acme Editor
Stars: ✭ 269 (-7.56%)
Mutual labels:  editor
A
A graphical text editor
Stars: ✭ 280 (-3.78%)
Mutual labels:  editor
Ggeditor
A visual graph editor based on G6 and React
Stars: ✭ 3,220 (+1006.53%)
Mutual labels:  editor
Edizon cheatsconfigsandscripts
The official EdiZon Editor Config and Editor Script repository.
Stars: ✭ 271 (-6.87%)
Mutual labels:  editor
Slingcode
personal computing platform
Stars: ✭ 277 (-4.81%)
Mutual labels:  editor
Josm
Mirror of @JOSM's Subversion repository
Stars: ✭ 282 (-3.09%)
Mutual labels:  editor
Wechat tweak
♨️ iOS版功能最全的微信插件,支持最新版微信,具备自动抢红包,屏蔽消息和群消息,过滤特定的群聊,防止撤回消息,伪定位 (朋友圈和附近的人),修改微信运动步数和实时取景做聊天页的背景等功能。
Stars: ✭ 265 (-8.93%)
Mutual labels:  hook
Micro
A modern and intuitive terminal-based text editor
Stars: ✭ 18,526 (+6266.32%)
Mutual labels:  editor
React Umeditor
React Editor like Umeditor
Stars: ✭ 279 (-4.12%)
Mutual labels:  editor
Netbeans Mmd Plugin
Free mind map and PlantUML editor with plugins for both NetBeans and Intellij
Stars: ✭ 283 (-2.75%)
Mutual labels:  editor
Radioactive State
☢ Make Your React App Truly Reactive!
Stars: ✭ 273 (-6.19%)
Mutual labels:  hook
Epic
Dynamic java method AOP hook for Android(continution of Dexposed on ART), Supporting 5.0~11
Stars: ✭ 3,434 (+1080.07%)
Mutual labels:  hook
Text
📑 Collaborative document editing using Markdown
Stars: ✭ 282 (-3.09%)
Mutual labels:  editor
Mak
A universal notepad. (WIP)
Stars: ✭ 270 (-7.22%)
Mutual labels:  editor
Swr
React Hooks for data fetching
Stars: ✭ 20,348 (+6892.44%)
Mutual labels:  hook
React Loads
React Loads is a backend agnostic library to help with external data fetching & caching in your UI components.
Stars: ✭ 268 (-7.9%)
Mutual labels:  hook
Xcodecolorsense2
🍉 An Xcode source editor extension that shows hex color info
Stars: ✭ 281 (-3.44%)
Mutual labels:  editor
Next Editor
Standalone Git Editor on Browser
Stars: ✭ 288 (-1.03%)
Mutual labels:  editor
Spacevim
A community-driven modular vim/neovim distribution - The ultimate vimrc
Stars: ✭ 17,558 (+5933.68%)
Mutual labels:  editor
React Native Rich Editor
Lightweight React Native (JavaScript, H5) rich text editor
Stars: ✭ 281 (-3.44%)
Mutual labels:  editor

use-editable

A small React hook to turn elements into fully renderable & editable content surfaces, like code editors, using contenteditable (and magic)


NPM Version License Minified gzip size

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!

Usage

First install use-editable alongside react:

yarn add use-editable
# or
npm install --save use-editable

You'll then be able to import useEditable and pass it an HTMLElement ref and an onChange handler.

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 (
    <div className="App">
      <pre
        style={{ whiteSpace: 'pre-wrap', fontFamily: 'monospace' }}
        ref={editorRef}
      >
        {code.split(/\r?\n/).map((content, i, arr) => (
          <React.Fragment key={i}>
            <span style={{ color: `hsl(${((i % 20) * 17) | 0}, 80%, 50%)` }}>
              {content}
            </span>
            {i < arr.length - 1 ? '\n' : null}
          </React.Fragment>
        ))}
      </pre>
    </div>
  );
};

And just like that we've hooked up useEditable to our editorRef, which points to the <pre> element that is being rendered, and to setCode which drives our state containing some code.

Browser Compatibility

This library has been tested against and should work properly using:

  • Chrome
  • Safari
  • iOS Safari
  • Firefox

There are known issues in IE 11 due to the MutationObserver method being unable to read text nodes that have been removed via the contenteditable.

FAQ

How does it work?

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 use contenteditable and render to raw HTML that is replaced in the element's content, or lastly one could combine a textarea with an overlapping div that renders stylised content.

All 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 contenteditable element so hard?

Typically 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 issue use-editable creates a MutationObserver, which watches over all changes that are made to the contenteditable element. Before it reports these changes to 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 for contenteditable editors, but the MutationObserver addition is what enables use-editable to let another view library update the element's content.

What's currently possible?

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 contenteditable's work, since they'll only capture the actual DOM content. Since use-editable doesn't aim to be a full component that manages the render cycle, it doesn't have to keep any extra state, but will only pass the DOM's text back to the onChange callback.

Using the onChange callback you'll also receive a Position object describing the cursor position, 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 the update function that useEditable returns to update the cursor position.

API

useEditable

The first argument is elementRef and accepts a ref object of type RefObject<HTMLElement> which points to the element that should become editable. This ref is allowed to be null or change during 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 onChange and accepts a callback of type (text: string, pos: Position) => void that's called whenever the content of the contenteditable changes. This needs to be set up so that it'll trigger a rerender of the element's contents.

The text that onChange receives is just the textual representation of the element's contents, while the Position it receives contains the current position of the cursor, the line number (zero-indexed), and the content of the current line up until the cursor, which is useful for autosuggestions.

The third argument is an optional options object. This accepts currently two options to change the editing behavior of the hook:

  • The disabled option disables editing on the editable by removing the contentEditable attribute from it again.
  • The indentation option may be a number of displayed spaces for indentation. This also enables the improved Tab key behavior which will indent the current line or dedent the current line when shift is held (Be aware that this will make the editor act as a focus trap!)

Additionally the useEditable hook returns a function that may be used to update the content while adjusting the next render's cursor position. This is a convenience method that can come in handy for adding auto-suggested content in combination with a Position's current line contents for instance.

Acknowledgments

  • react-live, which I've worked on had one of the early tiny contenteditable editors. (But with raw HTML updates)
  • react-simple-code-editor was the first (?) library to use a split textarea and rendering surface implementation, which presented what a nice editing API should look like.
  • codejar contains the best tricks to manage selections, although it lacks some Firefox workarounds. It also uses raw HTML highlighting / updating.
  • codemirror.next is an invaluable source to see different techniques when handling text input and DOM update tricks.
Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].