EditContext API

Multiple actors are involved when entering text in an editable region of an application:

User

The user provides the text by means of an input method: a keyboard, mouse, voice, or other input method.

Input method software

The input method software converts the user's input into text. For example, this could be an Input Method Editor (IME) that converts keystrokes from a standard keyboard into Japanese, Chinese, or Korean characters.

OS text input service

The text input service of the operating system acts as a link between the input method software and the application.

Application text edit context

The application text edit context provides a state of the text being edited. The state contains information such as the text itself, the current selection, the location of the text in the app's UI.

Application editable region

The application editable region is the UI element of the application that displays the text.

While the three first actors are provided by the operating system, the application is responsible for providing the editable region and the text edit context.

On the web, editable regions are often <textarea> elements, <input> elements, or elements with the contenteditable attribute set to true. For these elements, the browser automatically provides the text edit context, and web authors are not required to write any code to support text input.

Web authors can also create custom editable regions using the EditContext API. For example, a web author could create a rich text editor using a <canvas> element to render the text. In this case, the web author needs to write code to support text input.

If you decide to implement your own editable region, whether it draws text into a <canvas> or renders it into a series of DOM elements, you are responsible for providing the things that the browser would normally provide for you if you were using a <textarea> instead. This includes:

• Rendering the text.
• Rendering the selection (if you build your editable region with DOM elements instead of a <canvas>, the browser does render the selection for you).
• Letting the OS text input service know when the selection changes.
• Letting the OS text input service know where the text is located in the UI, so the input method software can display the IME composition window in the correct location.
• Applying certain text formats when the user is composing text within the IME composition window.

In return, the EditContext API makes the DOM element you choose editable and part of the document's focus order. In addition, the EditContext API also provides information about the state of the text being edited, which allows you to render it in a custom way. The information provided to you includes:

• The current text content.
• The current selection.
• Whether IME composition is in progress, and whether text formats need to be applied.

If you use the EditContext API with a <canvas> element, make sure to also make the text accessible to assistive technology. Screen readers can't read the text in a <canvas> element. For example, you could maintain a separate view of the text in an offscreen DOM element that's presented to screen readers.

To use the EditContext API, you need to create an instance of the EditContext interface, and then attach it to the DOM element you want to make editable by using the editContext property. The DOM element can be any element, including a <div> or a <canvas> element.

<canvas id="editor-canvas"></canvas>

const canvas = document.getElementById("editor-canvas");
const editContext = new EditContext();
canvas.editContext = editContext;

An EditContext instance can only be attached to one DOM element at a time.

Attaching an EditContext instance to a DOM element makes the element focusable, as part of the document's focus order. The user can enter text into the element using the input method of their choice, and you can use event fired by the EditContext instance to render the text and selection.

When using the EditContext API, it helps to build your editing experience as a model and view architecture.

The EditContext instance represents the model of your editable region. Its internal state gets updated when text input is received, and when the selection changes.

You can then render the text and selection in the view, using the information provided by the EditContext instance, however your view doesn't need to match the model exactly. You're free to render the text in any way you want.

EditContext Experimental

The EditContext interface is a JavaScript reflection of the text edit context that's normally provided transparently by the browser when using standard editable regions such as textarea. EditContext provides the state of the text being edited, with information such as the text itself, the current selection, or the location of the text in the app's UI.

TextFormat

The TextFormat interface is used to represent certain formats that should be applied to text ranges when the user is composing text within the IME composition window.

• Using the EditContext API