basecamp/trixPublic

NotificationsYou must be signed in to change notification settings
Fork1.1k
Star19.8k

A rich text editor for everyday writing

License

MIT license

19.8k stars 1.1k forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 2,944 Commits
.github		.github
assets		assets
bin		bin
src		src
.eslintrc		.eslintrc
.gitignore		.gitignore
.node-version		.node-version
.npmignore		.npmignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
babel.config.json		babel.config.json
karma.conf.js		karma.conf.js
package.json		package.json
rollup.config.js		rollup.config.js
yarn.lock		yarn.lock

Repository files navigation

Trix

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 fromBasecamp, the creators ofRuby 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 theall-new Basecamp 3.

Different By Design

Most WYSIWYG editors are wrappers around HTML’scontenteditable andexecCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, andeventually reverse-engineered and copied by other browsers.

Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies.

Trix sidesteps these inconsistencies by treatingcontenteditable 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 useexecCommand at all.

Built on Web standards

Trix supports all evergreen, self-updating desktop and mobile browsers.

Trix is built with established web standards, notablyCustom Elements,Mutation Observer, andPromises.

Getting Started

Trix comes bundled in ESM and UMD formats and works with any asset packaging system.

The easiest way to start with Trix is including it from an npm CDN in the<head> of your page:

<head>  …<linkrel="stylesheet"type="text/css"href="https://unpkg.com/trix@2.0.0/dist/trix.css"><scripttype="text/javascript"src="https://unpkg.com/trix@2.0.0/dist/trix.umd.min.js"></script></head>

trix.css includes default styles for the Trix toolbar, editor, and attachments. Skip this file if you prefer to define these styles yourself.

Alternatively, you can install the npm package and import it in your application:

importTrixfrom"trix"document.addEventListener("trix-before-initialize",()=>{// Change Trix.config if you need})

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<textarea>,<trix-editor> acceptsautofocus andplaceholder attributes. Unlike a<textarea>,<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 anid. Then reference thatid in the editor’sinput attribute.

<form…><inputid="x"type="hidden"name="content"><trix-editorinput="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’svalue attribute.

<form…><inputid="x"value="Editor content goes here"type="hidden"name="content"><trix-editorinput="x"></trix-editor></form>

Always use an associated input element to safely populate an editor. Trix won’t load any HTML content inside a<trix-editor>…</trix-editor> tag.

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.

<trix-editorclass="trix-content"></trix-editor>

<divclass="trix-content">Stored content here</div>

The defaulttrix.css file includes styles for basic formatted content—including bulleted and numbered lists, code blocks, and block quotes—under the class nametrix-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 consideredpending until you store it remotely and provide Trix with a permanent URL.

To store attachments, listen for thetrix-attachment-add event. Upload the attached files with XMLHttpRequest yourself and set the attachment’s URL attribute upon completion. See theattachment example for detailed information.

If you don’t want to accept dropped or pasted files, callpreventDefault() on thetrix-file-accept event, which Trix dispatches just before thetrix-attachment-add event.

Editing Text Programmatically

You can manipulate a Trix editor programmatically through theTrix.Editor interface, available on each<trix-editor> element through itseditor property.

varelement=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 adocument, and is represented as an instance of theTrix.Document class. To get the editor’s current document, use theeditor.getDocument method.

element.editor.getDocument()// is a Trix.Document instance

You can convert a document to an unformatted JavaScript string with thedocument.toString method.

vardocument=element.editor.getDocument()document.toString()// is a JavaScript string

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 thedocument.isEqualTo method.

vardocument=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 aposition, and a start and end position together make up arange.

To get the editor’s current selection, use theeditor.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 theeditor.setSelectedRange method.

// Select the first character in the documentelement.editor.setSelectedRange([0,1])

Collapsed Selections

When the start and end positions of a range are equal, the range is said to becollapsed. In the editor, a collapsed selection appears as a blinking cursor rather than a highlighted span of text.

For convenience, the following calls tosetSelectedRange are equivalent when working with collapsed selections:

element.editor.setSelectedRange(1)element.editor.setSelectedRange([1])element.editor.setSelectedRange([1,1])

Directional Movement

To programmatically move the cursor or selection through the document, call theeditor.moveCursorInDirection oreditor.expandSelectionInDirection methods with adirection argument. The direction can be either"forward" or"backward".

// Move the cursor backward one characterelement.editor.moveCursorInDirection("backward")// Expand the end of the selection forward by one characterelement.editor.expandSelectionInDirection("forward")

Converting Positions to Pixel Offsets

Sometimes you need to know thex andy 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.

Call theeditor.getClientRectAtPosition method with a position argument to get aDOMRect instance representing the left and top offsets, width, and height of the character at the given position.

varrect=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 theeditor.insertString method.

// Insert “Hello” at the beginning of the documentelement.editor.setSelectedRange([0,0])element.editor.insertString("Hello")

Inserting HTML

To insert HTML into the document, call theeditor.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 documentelement.editor.setSelectedRange([0,0])element.editor.insertHTML("<strong>Hello</strong>")

Inserting a File

To insert a DOMFile object into the document, call theeditor.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 elementvarfile=document.querySelector("input[type=file]").fileelement.editor.insertFile(file)

Inserting a Content Attachment

Content attachments are self-contained units of HTML that behave like files in the editor. They can be moved or removed, but not edited directly, and are represented by a single character position in the document model.

To insert HTML as an attachment, create aTrix.Attachment with acontent attribute and call theeditor.insertAttachment method. The HTML inside a content attachment is not subject to Trix’s document conversion rules and will be rendered as-is.

varattachment=newTrix.Attachment({content:'<span>@trix</span>'})element.editor.insertAttachment(attachment)

Inserting a Line Break

To insert a line break, call theeditor.insertLineBreak method, which is functionally equivalent to pressing the return key.

// Insert “Hello\n”element.editor.insertString("Hello")element.editor.insertLineBreak()

Deleting Text

If the current selection is collapsed, you can simulate deleting text before or after the cursor with theeditor.deleteInDirection method.

// “Backspace” the first character in the documentelement.editor.setSelectedRange([1,1])element.editor.deleteInDirection("backward")// Delete the second character in the documentelement.editor.setSelectedRange([1,1])element.editor.deleteInDirection("forward")

To delete a range of text, first set the selected range, then calleditor.deleteInDirection with either direction as the argument.

// Delete the first five characterselement.editor.setSelectedRange([0,4])element.editor.deleteInDirection("forward")

Working With Attributes and Nesting

Trix represents formatting as sets ofattributes applied across ranges of a document.

By default, Trix supports the inline attributesbold,italic,href, andstrike, and the block-level attributesheading1,quote,code,bullet, andnumber.

Applying Formatting

To apply formatting to the current selection, use theeditor.activateAttribute method.

element.editor.insertString("Hello")element.editor.setSelectedRange([0,5])element.editor.activateAttribute("bold")

To set thehref attribute, pass a URL as the second argument toeditor.activateAttribute.

element.editor.insertString("Trix")element.editor.setSelectedRange([0,4])element.editor.activateAttribute("href","https://trix-editor.org/")

Removing Formatting

Use theeditor.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 toeditor.insertString.

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 theeditor.increaseNestingLevel andeditor.decreaseNestingLevel methods.

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.

Call theeditor.undo andeditor.redo methods to perform an undo or redo operation.

element.editor.undo()element.editor.redo()

Changes you make through the editor interface will not automatically record undo entries. You can save your own undo entries by calling theeditor.recordUndoEntry method with a description argument.

element.editor.recordUndoEntry("Insert Text")element.editor.insertString("Hello")

Loading and Saving Editor State

Serialize an editor’s state withJSON.stringify and restore saved state with theeditor.loadJSON method. The serialized state includes the document and current selection, but does not include undo history.

// Save editor state to local storagelocalStorage["editorState"]=JSON.stringify(element.editor)// Restore editor state from local storageelement.editor.loadJSON(JSON.parse(localStorage["editorState"]))

Observing Editor Changes

The<trix-editor> element emits several events which you can use to observe and respond to changes in editor state.

trix-before-initialize fires when the<trix-editor> element is attached to the DOM just before Trix installs itseditor object. If you need to use a custom Trix configuration you can changeTrix.config here.
trix-initialize fires when the<trix-editor> element is attached to the DOM and itseditor object is ready for use.
trix-change fires whenever the editor’s contents have changed.
trix-paste fires whenever text is pasted into the editor. Thepaste property on the event contains the pastedstring orhtml, and therange of the inserted text.
trix-selection-change fires any time the selected range changes in the editor.
trix-focus andtrix-blur fire when the editor gains or loses focus, respectively.
trix-file-accept fires when a file is dropped or inserted into the editor. You can access the DOMFile object through thefile property on the event. CallpreventDefault on the event to prevent attaching the file to the document.
trix-attachment-add fires after an attachment is added to the document. You can access the Trix attachment object through theattachment property on the event. If theattachment object has afile property, you should store this file remotely and set the attachment’s URL attribute. See theattachment example for detailed information.
trix-attachment-remove fires when an attachment is removed from the document. You can access the Trix attachment object through theattachment property on the event. You may wish to use this event to clean up remotely stored files.

Contributing to Trix

Trix is open-source software, freely distributable under the terms of anMIT-style license. Thesource code is hosted on GitHub.

We welcome contributions in the form of bug reports, pull requests, or thoughtful discussions in theGitHub issue tracker. Please see theCode of Conduct for our pledge to contributors.

Trix was created byJavan Makhmali andSam Stephenson, with development sponsored byBasecamp.