Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

trix

A rich text editor for everyday writing

Subscribe to updates I use trix


Statistics on trix

Number of watchers on Github 8530
Number of open issues 52
Average time to close an issue 3 days
Main language CoffeeScript
Average time to merge a PR 1 day
Open pull requests 24+
Closed pull requests 33+
Last commit over 1 year ago
Repo Created about 6 years ago
Repo Last Updated over 1 year ago
Size 3.13 MB
Homepage https://trix-edit...
Organization / Authorbasecamp
Latest Release0.11.2
Contributors8
Page Updated
Do you use trix? Leave a review!
View open issues (52)
View trix activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating trix for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

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 liststhe 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 HTMLs contenteditable and 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.

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

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 supports all evergreen, self-updating desktop and mobile browsers.

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.

Getting Started

Include the bundled trix.css and trix.js files in the <head> of your page.

<head>

  <link rel="stylesheet" type="text/css" href="trix.css">
  <script type="text/javascript" src="trix.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.

To use your own polyfills, or to target only browsers that support all of the required standards, include trix-core.js instead.

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> accepts autofocus and placeholder 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 an id. Then reference that id in the editors input attribute.

<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 elements value attribute.

<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 wont 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-editor class="trix-content"></trix-editor>
<div class="trix-content">Stored content here</div>

The default trix.css file includes styles for basic formatted contentincluding bulleted and numbered lists, code blocks, and block quotesunder the class name trix-content. We encourage you to use these styles as a starting point by copying them into your applications 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 attachments URL attribute upon completion. See the attachment example for detailed information.

If you dont want to accept dropped or pasted files, call preventDefault() on the trix-file-accept event, which Trix dispatches just before the trix-attachment-add event.

Editing Text Programmatically

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

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 editors current document, use the editor.getDocument method.

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

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

var document = 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 editors 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 document.isEqualTo method.

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 editors 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 editors current selection by passing a range array to the editor.setSelectedRange method.

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

Collapsed Selections

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([1])
element.editor.setSelectedRange([1, 1])

Directional Movement

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

// 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 editors cursor.

Call the 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 editor.insertString method.

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

Inserting HTML

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()

Deleting Text

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

// 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 bold, italic, href, and strike, and the block-level attributes heading1, quote, code, bullet, and number.

Applying Formatting

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

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 editor.activateAttribute.

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

Removing Formatting

Use the 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 editor.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 the editor.increaseNestingLevel and editor.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 the editor.undo and editor.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 the editor.recordUndoEntry method with a description argument.

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

Loading and Saving Editor State

Serialize an editors 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

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

  • trix-initialize fires when the <trix-editor> element is attached to the DOM and its editor object is ready for use.

  • trix-change fires whenever the editors contents have changed.

  • trix-selection-change fires any time the selected range changes in the editor.

  • trix-focus and trix-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 DOM File object through the file property on the event. Call preventDefault 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 the attachment property on the event. If the attachment object has a file property, you should store this file remotely and set the attachments URL attribute. See the attachment example for detailed information.

  • trix-attachment-remove fires when an attachment is removed from the document. You can access the Trix attachment object through the attachment 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 an MIT-style license. The source code is hosted on GitHub.

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

Trix was created by Javan Makhmali and Sam Stephenson, with development sponsored by Basecamp.

Building From Source

Trix is written in CoffeeScript and compiled to JavaScript with Blade.

From inside a checkout of the Trix Git repository, issue the following commands to build the distributable files in dist/:

$ bin/setup
$ bin/blade build

Developing In-Browser

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.

Running Tests

Make sure youre 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.

Pull Requests

Only commit changes to Trixs source (everything except the compiled files in /dist) and leave the VERSION unchanged. We update both when publishing new releases. :heart:


2017 Basecamp, LLC.

trix open issues Ask a question     (View All Issues)
  • almost 3 years Plain-text only mode.
  • almost 3 years Code attibute "<>" doesn't quite work as it should
  • almost 3 years attachement visualization is failing
  • almost 3 years Automatically removes first Simplified Chinese character
  • almost 3 years Support tab character
  • almost 3 years Uploading Attached Files and Forms
  • almost 3 years Does Trix have an opinion on the future of Coffeescript?
  • almost 3 years iOS Siri dictation duplicates paragraphs
  • almost 3 years β€œInstant Smart Quotes” meets Trix
  • almost 3 years Buggy Undo Behavior with Blank Toolbar
  • almost 3 years rtl support
  • almost 3 years Allow shift-paste to be format-less pasting
  • about 3 years Text align justify
  • about 3 years Delete word shortcut (Option+Backspace) on a word does not work on elements that have styling
  • about 3 years Firefox replaces space after deleting word
  • over 3 years Cannot remove blank line before block element without removing the style
  • over 3 years Bug: additional <br> is created if the value ends with <br>
  • over 3 years Use p tag instead of div for regular block content
  • over 3 years Cannot remove image when caption field is focused
  • over 3 years When editor is focused, text is not accessible with JAWS and Firefox
  • over 3 years InputController `backspace` will never fire on Android browsers, causes issues deleting attachments
  • over 3 years Text-Cursors stays in Editor when user tabs out.
  • over 3 years background-color: highlight added to selected content when adding a link
  • over 3 years Can't input korean character.
  • over 3 years Support different configs for different trix editor on same page
  • over 3 years Add a mobile-friendly UX for the toolbar
  • over 3 years Necessary HTML tags and attributes for Trix
  • over 3 years Enter image caption via keyboard
  • over 3 years Set shim issues
  • almost 4 years Make caption for previewable attachments optional
trix open pull requests (View All Pulls)
  • Create a new block when the user presses return
  • Fix for issue with ancestor table nodes (td-tag) outside of the trix-…
  • Update README to include npm info
  • CSS clean-up
  • singleLine option for blocks
  • Leaf option for blocks
  • Configurable toolbar and formatting attributes
  • Allow adding captions to previewable attachments with no filename
  • Natural white space
  • Move Trix explicitly on to the `window` object
  • Fix typing formatted text after a newline at the end of a block
  • Paragraphs and figures
  • Headers
  • Add header support
  • CSS Reboot
  • Handle unexpected newline in mutationIsExpected
  • Fix serializing after composition input
  • allow the input element name to be updated
  • Remove toolbar buttons from the navigation flow
  • Deleting in-line attachments
  • Fix Safari image pasting
  • Replace broken Promises link
  • Add markup for better JAWS and NVDA screenreader performance
  • Image attachment sizes
trix questions on Stackoverflow (View All Questions)
  • Trix Editor save changes
  • Fuseki2 and TriX format
trix list of languages used
trix latest release notes
  • Add support for Chrome 65s questionable composition event changes on Android (https://github.com/basecamp/trix/pull/487)
  • Fix occasional multibyte character (emoji, basically) breakage on iOS (https://github.com/basecamp/trix/pull/439)
  • Fix cursor position when pasting HTML in an expanded selection (https://github.com/basecamp/trix/commit/3a3f1896ab1bfa16e81cc2fefd582f5d5a285c8d)
  • Fix accessibility issue where pressing tab would incorrectly move focus to a linked attachment instead of the next form element (https://github.com/basecamp/trix/commit/3a3f1896ab1bfa16e81cc2fefd582f5d5a285c8d)
  • Fix editing upload-in-progress attachment captions (https://github.com/basecamp/trix/pull/445)
  • Fix pasting in MS Edge (https://github.com/basecamp/trix/issues/452)
  • Improve displaying code blocks in list items (https://github.com/basecamp/trix/pull/450)
  • Add support for configuring attachment captions (https://github.com/basecamp/trix/pull/434)
  • Update attachment and toolbar CSS and related configuration (https://github.com/basecamp/trix/pull/435)
  • Improve pastes from Microsoft Word (8bc9ee2a2f9b896426ef29ed4875f2f413c1328c, b5d1bddbba9a0e819e8e3e64b08150b903234de8)
  • Improve URL pastes in Safari (19bc507c17f2d9070cd5193d843dc1b3ebd36fba)
Other projects in CoffeeScript