# JavaScript API

> Use the Document Editor's global TXTextControl object in every frontend: init settings, textControlLoaded, callbacks, error handling, promises and collections.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Document Editor > JavaScript API
- **3993 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/javascript-api/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/javascript-api/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/javascript-api/llms-full.txt

---

The pages about tables, fields, track changes and the other features of the Document Editor all build on the concepts of its JavaScript API. Before you write code that changes the document, get to know the `TXTextControl` object, when your code can use it, how its asynchronous methods return results and how its objects are organized.

### What the JavaScript API Is

The Document Editor adds a global object named [TXTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/llms-full.txt) to the page. Its properties and methods give your code access to the document in the editor: the text and its formatting, tables, images, fields, sections, tracked changes and comments, the current selection and the input position. Its events tell your code what the user does.

All frontends use the same component in the browser, so the API is the same in an ASP.NET Core view, a plain JavaScript page, an Angular or React application and a Blazor page. Only the moment when the object becomes available differs.

The Document Viewer has an API of its own, the `TXDocumentViewer` object; see [Document Viewer](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/components/document-viewer/llms-full.txt).

### When the Object Is Available

Two moments matter: when the `TXTextControl` object exists, so that your code can attach event handlers, and when the editor raises `textControlLoaded`, after which your code can change the document.

| Frontend | The object exists | Where your code goes |
|---|---|---|
| ASP.NET Core | When the page has loaded | A `<script>` element in the view, below the editor. See [ASP.NET Core](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/aspnet-core/llms-full.txt). |
| JavaScript | When the editor script from the backend has loaded | After the call of `TXTextControl.init`. See [JavaScript](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/javascript/llms-full.txt). |
| Angular | When the `txDocumentEditorLoaded` event is raised on `document` | In a handler of this event, with `declare const TXTextControl: any;`. See [Angular](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/angular/llms-full.txt). |
| React | When the function of the `onLoad` property runs | In this function. See [React](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/react/llms-full.txt). |
| Blazor | In the page that contains the component | JavaScript in the page. See [Blazor](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/blazor/llms-full.txt). |

In every frontend, wait for `textControlLoaded` before you read or change the document:

```javascript
TXTextControl.addEventListener("textControlLoaded", function () {
  // The editor is ready: the document can be read and changed from here on
  TXTextControl.selection.setText("Hello from the JavaScript API");
});
```

[Events](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/events/llms-full.txt) describes the order of the events during initialization.

### Settings of TXTextControl.init

In a plain JavaScript page, [TXTextControl.init](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/init-method/llms-full.txt) creates the editor from a [ComponentSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/llms-full.txt) object, and its `editorSettings` property holds a [DocumentEditorSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/llms-full.txt) object. Both were added in version 32.0. The [JavaScript](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/javascript/llms-full.txt) tutorial shows the call.

| `ComponentSettings` property | Sets |
|---|---|
| [containerID](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/containerid-property/llms-full.txt), [containerElement](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/containerelement-property/llms-full.txt) | The `div` element the editor is placed in, by its ID or as the element; `containerID` is always required, also when `containerElement` is set, and `containerElement` wins if both are set |
| [webSocketURL](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/websocketurl-property/llms-full.txt) | The WebSocket URL of the backend; required |
| [replaceContainer](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/replacecontainer-property/llms-full.txt) | `true` replaces the container element with the editor instead of adding the editor to it as a child |
| [domContentLoaded](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/domcontentloaded-property/llms-full.txt) | A function that is called as soon as the elements of the editor have been inserted into the page |
| [editorSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/componentsettings/editorsettings-property/llms-full.txt) | The `DocumentEditorSettings` below |

| `DocumentEditorSettings` property | Sets |
|---|---|
| [editMode](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/editmode-property/llms-full.txt) | Whether the text is read-only, can be selected or can be edited, a value of [EditMode](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/editmode-enumeration/llms-full.txt) |
| [userNames](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/usernames-property/llms-full.txt) | The users who can edit their editable regions of a read-only document |
| [culture](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/culture-property/llms-full.txt), [uiCulture](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/uiculture-property/llms-full.txt) | The culture of formats such as dates, and the language of the user interface |
| [contextMenusEnabled](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/contextmenusenabled-property/llms-full.txt) | Whether a right-click opens a context menu |
| [reconnectTimeout](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/reconnecttimeout-property/llms-full.txt) | How many seconds the editor tries to reconnect after the connection is lost |
| [connectionID](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/connectionid-property/llms-full.txt) | A unique ID string of the connection |
| [webSocketProtocols](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/websocketprotocols-property/llms-full.txt) | Additional WebSocket subprotocols, for example to pass an authentication token |
| [customQueryParams](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/customqueryparams-property/llms-full.txt) | An object of custom query parameters |
| [formattingPrinter](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/documenteditorsettings/formattingprinter-property/llms-full.txt) | The name of a printer whose text dimensions format the document |

The formatting printer, like [setFormattingPrinter](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/setformattingprinter-method/llms-full.txt), is only used by the Windows-based synchronization service of earlier versions. The platform-independent backend of the current version doesn't support printer-specific formatting, so the setting has no effect there; see [Viewing and Printing](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/viewing-printing/#print-the-document).

### Callbacks

Many methods of the API are asynchronous. They don't return a value; instead, they take a callback function that receives the result when it is available:

```javascript
function showSelection() {
  TXTextControl.selection.getStart(function (start) {
    TXTextControl.selection.getLength(function (length) {
      console.log("The selection starts at " + start + " and is " + length + " characters long");
    });
  });
}
```

- [Selection.getStart](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/selection/getstart-method/llms-full.txt) passes the start position of the selection to its callback.
- The second call runs inside the first callback, because it needs the result of the first. Code after `getStart` in the same function would run before the callback.
- Methods that return nothing, such as most set methods, take an optional callback that is called when the operation has completed. Use it when the next step depends on the change.

Some members return their result directly: [btoaUTF8](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/btoautf8-method/llms-full.txt) and [atobUTF8](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/atobutf8-method/llms-full.txt) encode and decode strings, and properties such as [TXTextControl.selection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/selection-property/llms-full.txt) return objects directly.

#### Handle Errors

Many methods take an optional error callback as their last parameter. It receives an [ErrorArgument](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/errorargument/llms-full.txt) with the error message in [msg](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/errorargument/msg-property/llms-full.txt). By default, an error that isn't handled is thrown. Set [handled](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/errorargument/handled-property/llms-full.txt) to `true` to stop that:

```javascript
function getTableCount() {
  TXTextControl.tables.getCount(function (count) {
    console.log(count + " tables");
  }, function (error) {
    console.log("Failed: " + error.msg);
    error.handled = true; // don't throw the error
  });
}
```

The `unhandledError` event is raised before an error is thrown, so a single handler can log all errors that no error callback handles.

### Promises and async/await

The API has no methods that return promises. When several calls depend on each other, nested callbacks become hard to read. Wrap a call in a `Promise` and use `async` and `await` instead:

```javascript
function getSelectionRange() {
  return new Promise(function (resolve, reject) {
    TXTextControl.selection.getStart(function (start) {
      TXTextControl.selection.getLength(function (length) {
        resolve({ start: start, length: length });
      }, reject);
    }, reject);
  });
}

async function logSelection() {
  var range = await getSelectionRange();
  console.log(range.start + ", " + range.length);
}
```

Awaiting each step also keeps the order: calls that are sent one after another without waiting aren't guaranteed to complete in that order. This matters especially when a loop changes the text of many elements. The blog article [New JavaScript API: Working with Callbacks and Promises](https://www.textcontrol.com/blog/2020/03/26/working-with-callbacks-and-promises/) explains the pattern.

### The Object Model

#### Text Parts

A document consists of text parts: the main text, the headers and footers and the text frames. Each text part is a [FormattedText](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/llms-full.txt) object, which provides the collections of that part, such as [tables](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/tables-property/llms-full.txt), [paragraphs](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/paragraphs-property/llms-full.txt), [textFields](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/textfields-property/llms-full.txt), [formFields](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/formfields-property/llms-full.txt), [trackedChanges](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/trackedchanges-property/llms-full.txt) and [comments](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/formattedtext/comments-property/llms-full.txt), and its own `selection`.

`TXTextControl` itself inherits from `FormattedText` and represents the main text. `TXTextControl.tables` therefore returns the tables of the main text, while a [HeaderFooter](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/headerfooter/llms-full.txt) or a [TextFrame](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/textframe/llms-full.txt) returns its own tables through the same property. In the reference, these inherited members are documented on the `FormattedText` page.

#### Collections

Collections such as [TableCollection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/tablecollection/llms-full.txt) or [SectionCollection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/sectioncollection/llms-full.txt) derive from [Collection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/collection/llms-full.txt), which provides three methods:

- [getCount](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/collection/getcount-method/llms-full.txt) passes the number of elements to its callback.
- [elementAt](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/collection/elementat-method/llms-full.txt) passes the element at an index.
- [forEach](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/collection/foreach-method/llms-full.txt) calls a function for each element with the element, its index and the number of elements.

Each collection adds its own methods, such as `add`, `getItem` and `remove`.

#### Objects of the Main Text

Besides the inherited collections, `TXTextControl` has properties for the whole document, for example:

| Property | Returns |
|---|---|
| [selection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/selection-property/llms-full.txt) | The current [Selection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/selection/llms-full.txt), with its text and formatting |
| [inputPosition](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/inputposition-property/llms-full.txt) | The [InputPosition](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/inputposition/llms-full.txt): page, line, column and text position of the cursor |
| [sections](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/sections-property/llms-full.txt) | The sections of the document |
| [headersAndFooters](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/headersandfooters-property/llms-full.txt) | All headers and footers of the document |
| [images](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/images-property/llms-full.txt) and [textFrames](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/textframes-property/llms-full.txt) | The images of the text part with the input focus, and all text frames of the document |
| [textParts](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/textparts-property/llms-full.txt) | All text parts: the main text, the text frames and the headers and footers |
| [ribbon](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/ribbon-property/llms-full.txt) | The ribbon bar |

To select text, assign an object with the start position and the length: `TXTextControl.selection = { start: 2, length: 5 };`. A [SubTextPart](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/subtextpart/llms-full.txt) is a part of the text that your code defines, to work with a smaller piece of the document. [Editing Text](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/editing-text/llms-full.txt) and [Subtext Parts](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/subtext-parts/llms-full.txt) describe both.

#### Enumerations

Enumerations are properties of the `TXTextControl` object, for example `TXTextControl.StreamType.WordprocessingML` or `TXTextControl.HighlightMode.Always`. Pass these names instead of numbers.

#### Obsolete Members

Some older properties are marked obsolete in the reference and will be removed. They have been replaced by get and set methods, which follow the callback model: use [setIsTrackChangesEnabled](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/setistrackchangesenabled-method/llms-full.txt) instead of the `isTrackChangesEnabled` property, and [setEditMode](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/seteditmode-method/llms-full.txt) instead of `editMode`. The event `textControlChanged` is obsolete as well; use `changed`. Articles written for older versions still use some of these members.

### Group Changes Into One Undo Step

When your code makes several changes, each one is a step of its own for the user's undo command. Call [beginUndoAction](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/beginundoaction-method/llms-full.txt) with a name before the changes and [endUndoAction](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/endundoaction-method/llms-full.txt) after them, and all changes in between are undone and redone in one step.

### Remove the Editor

In a single-page application, the page isn't reloaded when the user navigates to another view. Before you remove the editor from the page or create it again, call [removeFromDom](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/removefromdom-method/llms-full.txt). It closes the WebSocket connection gracefully and removes the editor with its event handlers and CSS references. If your code adds the editor script to the page dynamically, remove its `script` element as well before you load it again.

### Find Members in the Reference

The [JavaScript API reference](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/llms-full.txt) lists every object with its properties, methods, callbacks and enumerations. For each method, it documents the parameters in their order, which parameters are optional, and the callback type with the value it receives. The members that a version added are listed on the What's New pages, for example [Version 34.0](https://docs.textcontrol.com/tx-text-control-dotnet-server/whats-new/3400/llms-full.txt).

### Next Steps

- [Events](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/events/llms-full.txt): react to what users do in the editor.
- [Loading and Saving Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/load-save/llms-full.txt): load and save documents from JavaScript.
- [Text and Paragraph Formatting](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/formatting/llms-full.txt): format the selection.
- [Tables](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/tables/llms-full.txt): add and change tables.

---

## Nearby

- **Previous:** [Localization](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/ribbon-ui/localization/llms-full.txt)
- **Next:** [Events](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/events/llms-full.txt)