trix

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 from 37signals, the creators of Ruby on Rails. Millions of people trust their text to us, and we built Trix to give them the best possible editing experience. See Trix in action in Basecamp. Different By Design When Trix was designed in 2014, most WYSIWYG editors were wrappers around HTML’s 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 not 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 sidestepped 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. This is the approach that all modern, production ready, WYSIWYG editors now take. Built on Web standards Trix supports all evergreen, self-updating desktop and mobile browsers. Trix is built with established web standards, notably Custom Elements, Element Internals, Mutation Observer, and Promises. 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> … <link rel="stylesheet" type="text/css" href="https://unpkg.com/trix@2.0.8/dist/trix.css"> <script type="text/javascript" src="https://unpkg.com/trix@2.0.8/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: import Trix from "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> accepts autofocus and placeholder attributes. Unlike a <textarea>, <trix-editor> automatically expands vertically to fit its contents. Creating a Toolbar Trix automatically will create a toolbar for you and attach it right before the <trix-editor> element. If you'd like to place the toolbar in a different place you can use the toolbar attribute: <main> <trix-toolbar id="my_toolbar"></trix-toolbar> <div class="more-stuff-inbetween"></div> <trix-editor toolbar="my_toolbar" input="my_input"></trix-editor> </main> To change the toolbar without modifying Trix, you can overwrite the Trix.config.toolbar.getDefaultHTML() function. The default toolbar HTML is in config/toolbar.js. Trix uses data attributes to determine how to respond to a toolbar button click. Toggle Attribute With data-trix-attribute="<attribute name>", you can add an attribute to the current selection. For example, to apply bold styling to the selected text the button is: <button type="button" class="bold" data-trix-attribute="bold" data-trix-key="b"></button> Trix will determine that a range of text is selected and will apply the formatting defined in Trix.config.textAttributes (found in config/text_attributes.js). data-trix-key="b" tells Trix that this attribute should be applied when you use meta+b. If the attribute is defined in Trix.config.blockAttributes, Trix will apply the attribute to the current block of text. <button type="button" class="quote" data-trix-attribute="quote"></button> Clicking the quote button toggles whether the block should be rendered with <blockquote>. Integrating with Element Internals Trix will integrate <trix-editor> elements with forms depending on the browser's support for Element Internals. If there is a need to disable support for ElementInternals, set Trix.elements.TrixEditorElement.formAssociated = false: import Trix from "trix" Trix.elements.TrixEditorElement.formAssociated = false When Trix is configured to be compatible with ElementInternals, it is also capable of functioning without an <input type="hidden"> element. To configure a <trix-editor> element to skip creating its <input type="hidden">, set the element's willCreateInput = false: addEventListener("before-trix-initialize", (event) => { const trixEditor = event.target trixEditor.willCreateInput = false }) NoteTrix will always use an associated <input type="hidden"> element when the [input] attribute is set. To migrate to <input>-free support, set willCreateInput = false, then render the <trix-editor> without the [input] attribute. WarningIn the absence of an <input type="hidden"> element, the <trix-editor> element's value will not be included in <form> element submissions unless it is rendered with a [name] attribute. Set the [name] attribute to the same value that the <input type="hidden"> element would have. Invoking Internal Trix Actions Internal actions are defined in controllers/editor_controller.js and consist of: undo redo link increaseBlockLevel decreaseBlockLevel <button type="button" class="block-level decrease" data-trix-action="decreaseBlockLevel"></button> Invoking External Custom Actions If you want to add a button to the toolbar and have it invoke an external action, you can prefix your action name with x-. For example,