A Rich Text Editor for Everyday Writing
Compose beautifully formatted text in your web application. Trix is a WYSIWYG editor for writing messages, comments, articles, and lists—the simple documents most web apps are made of. It features a sophisticated document model, support for embedded attachments, and outputs terse and consistent HTML.
Trix is an open-source project from Basecamp, the creators of Ruby on Rails. Millions of people trust their text to Basecamp, and we built Trix to give them the best possible editing experience. See Trix in action in the all-new Basecamp 3.
Different By Design
Most WYSIWYG editors are wrappers around HTML’s
execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers.
Trix sidesteps these inconsistencies by treating
contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use
execCommand at all.
Built for the Modern Web
Trix is built with emerging web standards, notably Custom Elements, Mutation Observer, and Promises. Eventually we expect all browsers to implement these standards. In the meantime, Trix includes polyfills for missing functionality.
Include the bundled
trix.js files in the
<head> of your page.
trix.css includes default styles for the Trix toolbar, editor, and attachments. Skip this file if you prefer to define these styles yourself.
To use your own polyfills, or to target only browsers that support all of the required standards, include
Creating an Editor
Place an empty
<trix-editor></trix-editor> tag on the page. Trix will automatically insert a separate
<trix-toolbar> before the editor.
Like an HTML
placeholder attributes. Unlike a
<trix-editor> automatically expands vertically to fit its contents.
Integrating With Forms
To submit the contents of a
<trix-editor> with a form, first define a hidden input field in the form and assign it an
id. Then reference that
id in the editor’s
<form …> <input id="x" type="hidden" name="content"> <trix-editor input="x"></trix-editor> </form>
Trix will automatically update the value of the hidden input field with each change to the editor.
Populating With Stored Content
To populate a
<trix-editor> with stored content, include that content in the associated input element’s
<form …> <input id="x" value="Editor content goes here" type="hidden" name="content"> <trix-editor input="x"></trix-editor> </form>
Always use an associated input element to safely populate an editor. Trix won’t load any HTML content inside a
Styling Formatted Content
To ensure what you see when you edit is what you see when you save, use a CSS class name to scope styles for Trix formatted content. Apply this class name to your
<trix-editor> element, and to a containing element when you render stored Trix content for display in your application.
<div class="trix-content">Stored content here</div>
trix.css file includes styles for basic formatted content—including bulleted and numbered lists, code blocks, and block quotes—under the class name
trix-content. We encourage you to use these styles as a starting point by copying them into your application’s CSS with a different class name.
Storing Attached Files
Trix automatically accepts files dragged or pasted into an editor and inserts them as attachments in the document. Each attachment is considered pending until you store it remotely and provide Trix with a permanent URL.
To store attachments, listen for the
trix-attachment-add event. Upload the attached files with XMLHttpRequest yourself and set the attachment’s URL attribute upon completion. See the attachment example for detailed information.
If you don’t want to accept dropped or pasted files, call
preventDefault() on the
trix-file-accept event, which Trix dispatches just before the
Editing Text Programmatically
You can manipulate a Trix editor programmatically through the
Trix.Editor interface, available on each
<trix-editor> element through its
var element = document.querySelector("trix-editor") element.editor // is a Trix.Editor instance
Understanding the Document Model
The formatted content of a Trix editor is known as a document, and is represented as an instance of the
Trix.Document class. To get the editor’s current document, use the
element.editor.getDocument() // is a Trix.Document instance
Immutability and Equality
Documents are immutable values. Each change you make in an editor replaces the previous document with a new document. Capturing a snapshot of the editor’s content is as simple as keeping a reference to its document, since that document will never change over time. (This is how Trix implements undo.)
To compare two documents for equality, use the
var document = element.editor.getDocument() document.isEqualTo(element.editor.getDocument()) // true
Getting and Setting the Selection
Trix documents are structured as sequences of individually addressable characters. The index of one character in a document is called a position, and a start and end position together make up a range.
To get the editor’s current selection, use the
editor.getSelectedRange method, which returns a two-element array containing the start and end positions.
element.editor.getSelectedRange() // [0, 0]
You can set the editor’s current selection by passing a range array to the
// Select the first character in the document element.editor.setSelectedRange([0, 1])
When the start and end positions of a range are equal, the range is said to be collapsed. In the editor, a collapsed selection appears as a blinking cursor rather than a highlighted span of text.
For convenience, the following calls to
setSelectedRange are equivalent when working with collapsed selections:
element.editor.setSelectedRange(1) element.editor.setSelectedRange() element.editor.setSelectedRange([1, 1])
To programmatically move the cursor or selection through the document, call the
editor.expandSelectionInDirection methods with a direction argument. The direction can be either
// Move the cursor backward one character element.editor.moveCursorInDirection("backward") // Expand the end of the selection forward by one character element.editor.expandSelectionInDirection("forward")
Converting Positions to Pixel Offsets
Sometimes you need to know the x and y coordinates of a character at a given position in the editor. For example, you might want to absolutely position a pop-up menu element below the editor’s cursor.
editor.getClientRectAtPosition method with a position argument to get a
DOMRect instance representing the left and top offsets, width, and height of the character at the given position.
var rect = element.editor.getClientRectAtPosition(0) [rect.left, rect.top] // [17, 49]
Inserting and Deleting Text
The editor interface provides methods for inserting, replacing, and deleting text at the current selection.
To insert or replace text, begin by setting the selected range, then call one of the insertion methods below. Trix will first remove any selected text, then insert the new text at the start position of the selected range.
Inserting Plain Text
To insert unformatted text into the document, call the
// Insert “Hello” at the beginning of the document element.editor.setSelectedRange([0, 0]) element.editor.insertString("Hello")
To insert HTML into the document, call the
editor.insertHTML method. Trix will first convert the HTML into its internal document model. During this conversion, any formatting that cannot be represented in a Trix document will be lost.
// Insert a bold “Hello” at the beginning of the document element.editor.setSelectedRange([0, 0]) element.editor.insertHTML("<strong>Hello</strong>")
Inserting a File
To insert a DOM
File object into the document, call the
editor.insertFile method. Trix will insert a pending attachment for the file as if you had dragged and dropped it onto the editor.
// Insert the selected file from the first file input element var file = document.querySelector("input[type=file]").file element.editor.insertFile(file)
Inserting a Line Break
To insert a line break, call the
editor.insertLineBreak method, which is functionally equivalent to pressing the return key.
// Insert “Hello\n” element.editor.insertString("Hello") element.editor.insertLineBreak()
If the current selection is collapsed, you can simulate deleting text before or after the cursor with the
// “Backspace” the first character in the document element.editor.setSelectedRange([1, 1]) element.editor.deleteInDirection("backward") // Delete the second character in the document element.editor.setSelectedRange([1, 1]) element.editor.deleteInDirection("forward")
To delete a range of text, first set the selected range, then call
editor.deleteInDirection with either direction as the argument.
// Delete the first five characters element.editor.setSelectedRange([0, 4]) element.editor.deleteInDirection("forward")
Working With Attributes and Nesting
Trix represents formatting as sets of attributes applied across ranges of a document.
By default, Trix supports the inline attributes
strike, and the block-level attributes
To apply formatting to the current selection, use the
element.editor.insertString("Hello") element.editor.setSelectedRange([0, 5]) element.editor.activateAttribute("bold")
To set the
href attribute, pass a URL as the second argument to
element.editor.insertString("Trix") element.editor.setSelectedRange([0, 4]) element.editor.activateAttribute("href", "https://trix-editor.org/")
editor.deactivateAttribute method to remove formatting from a selection.
element.editor.setSelectedRange([2, 4]) element.editor.deactivateAttribute("bold")
Formatting With a Collapsed Selection
If you activate or deactivate attributes when the selection is collapsed, your formatting changes will apply to the text inserted by any subsequent calls to
element.editor.activateAttribute("italic") element.editor.insertString("This is italic")
Adjusting the Nesting Level
To adjust the nesting level of quotes, bulleted lists, or numbered lists, call the
element.editor.activateAttribute("quote") element.editor.increaseNestingLevel() element.editor.decreaseNestingLevel()
Using Undo and Redo
Trix editors support unlimited undo and redo. Successive typing and formatting changes are consolidated together at five-second intervals; all other input changes are recorded individually in undo history.
editor.redo methods to perform an undo or redo operation.
Changes you make through the editor interface will not automatically record undo entries. You can save your own undo entries by calling the
editor.recordUndoEntry method with a description argument.
element.editor.insertString("Hello") element.editor.recordUndoEntry("Insert Text")
Loading and Saving Editor State
Serialize an editor’s state with
JSON.stringify and restore saved state with the
editor.loadJSON method. The serialized state includes the document and current selection, but does not include undo history.
// Save editor state to local storage localStorage["editorState"] = JSON.stringify(element.editor) // Restore editor state from local storage element.editor.loadJSON(JSON.parse(localStorage["editorState"]))
Observing Editor Changes
<trix-editor> element emits several events which you can use to observe and respond to changes in editor state.
trix-initializefires when the
<trix-editor>element is attached to the DOM and its
editorobject is ready for use.
trix-changefires whenever the editor’s contents have changed.
trix-selection-changefires any time the selected range changes in the editor.
trix-blurfire when the editor gains or loses focus, respectively.
trix-file-acceptfires when a file is dropped or inserted into the editor. You can access the DOM
Fileobject through the
fileproperty on the event. Call
preventDefaulton the event to prevent attaching the file to the document.
trix-attachment-addfires after an attachment is added to the document. You can access the Trix attachment object through the
attachmentproperty on the event. If the
attachmentobject has a
fileproperty, you should store this file remotely and set the attachment’s URL attribute. See the attachment example for detailed information.
trix-attachment-removefires when an attachment is removed from the document. You can access the Trix attachment object through the
attachmentproperty on the event. You may wish to use this event to clean up remotely stored files.
Contributing to Trix
Building From Source
From inside a checkout of the Trix Git repository, issue the following commands to build the distributable files in
$ bin/setup $ bin/blade build
You can spawn a development web server to work on Trix in a more convenient fashion. Instead of manually rebuilding the source each time, just reload a page in your browser to see your changes.
To develop in-browser, run
bin/setup and follow the displayed instructions.
Make sure you’re set up to build from source using the instructions above. Then run
bin/blade runner and visit the displayed URL to run the Trix test suite.
© 2017 Basecamp, LLC.