lightning:inputRichText (Beta)

A WYSIWYG editor with a customizable toolbar for entering rich text.

A lightning:inputRichText component creates a rich text editor based on the Quill JS library, enabling you to add, edit, format, and delete rich text. You can create multiple rich text editors with different toolbar configurations. Pasting rich content into the editor is supported if the feature is available in the toolbar. For example, you can paste bold text if the bold button is available in the toolbar. An overflow menu is provided if more toolbar buttons are available than can fit the width of the toolbar.

This component inherits styling from rich text editor in the Lightning Design System.

This example creates a rich text editor and sets its content during initialization.

<aura:component>
    <aura:attribute name="myVal" type="String" />
    <aura:handler name="init" value="{! this }" action="{! c.init }"/>
    <lightning:inputRichText value="{!v.myVal}" />
</aura:component>

Initialize the rich text content in the client-side controller.

({
    init: function(cmp) {
        cmp.set('v.myVal', '<b>Hello!</b>');
    }
})
Customizing the Toolbar

By default, the toolbar displays the font family and size menu, the format text block with Bold, Italic, Underline, and Strikethrough buttons. It also displays the format body block with Bulleted List, Numbered List, Indent, and Outdent buttons, followed by the align text block with Left Align Text, Center Align Text, and Right Align Text buttons. The Remove Formatting button is also available, and it always stands alone at the end of the toolbar.

You can disable buttons by category using the disabledCategories attribute. The categories are:

  1. FORMAT_FONT: Format font family and size menus
  2. FORMAT_TEXT: Format text buttons
  3. FORMAT_BODY: Format body buttons
  4. ALIGN_TEXT: Align text buttons
  5. REMOVE_FORMATTING: Remove formatting buttons

The font menu provides the following font selection: Arial, Courier, Garamond, Salesforce Sans, Tahoma, Times New Roman, and Verdana. The font selection defaults to Salesforce Sans with a size of 12px. Supported font sizes are: 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 26, 28, 36, 48, and 72. When you copy and paste text in the editor, the font is preserved only if the font is available in the font menu.

Input Validation

lightning:inputRichText doesn't provide built-in validation but you can wire up your own validation logic. Set the valid attribute to false to change the border color of the rich text editor to red. This example checks whether the rich text content is empty or undefined.

<aura:component>
    <aura:attribute name="myVal" type="String" />
    <aura:attribute name="errorMessage" type="String" default="You haven't composed anything yet."/>
    <aura:attribute name="validity" type="Boolean" default="true"/>
    <lightning:inputRichText value="{!v.myVal}" placeholder="Type something interesting" messageWhenBadInput="{!v.errorMessage}" valid="{!v.validity}"/>
    <lightning:button name="validate" label="Validate" onclick="{!c.validate}"/>
</aura:component>

The client-side controller toggles the validity of the rich text editor, and displays the error message when it's invalid.

({
    validate: function(cmp) {
        if(!cmp.get("v.myVal")){
            cmp.set("v.validity", false);
        }
        else{
            cmp.set("v.validity", true);
        }
    }
})
Supported HTML Tags

The rich text editor provides a WYSIWYG interface only. You can't edit HTML tags using the editor, but you can set the HTML tags via the value attribute. When you copy content from a web page or another source and paste it into the editor, unsupported tags are removed. Only formatting that corresponds to an enabled toolbar button or menu is preserved. For example, if you disable the FORMAT_TEXT category, the Bold, Italic, Underline, and Strikethrough buttons are not available. Furthermore, pasting bold, italic, underlined, or strikethrough text in the editor are not supported when you disable the FORMAT_TEXT category. Text that was enclosed in unsupported tags is preserved as plain text. However, tables, images, and links can be pasted into the editor and set via the value attribute, even though there are no corresponding toolbar buttons or menus for them.

The component sanitizes HTML tags passed to the value attribute to prevent XSS vulnerabilities. Only HTML tags that correspond to features available on the toolbar are supported. If you set unsupported tags via a client-side controller, those tags are removed and the text content is preserved. The supported HTML tags are: a, b, col, colgroup, em (converted to i), h1, h2, h3, h4, h5, h6, i, img, li, ol, p, q, s, strike (converted to s), strong, table, tbody, td, tfoot, th, thead, tr, u, ul, strike.

Pasting text enclosed in div and span tags convert those tags to p tags. Let’s say you paste or set some text in the editor that looks like this.

The sky is <span style="color:blue;font-weight:bold">blue</span>.
<div style="color:#0000FF;font-weight:bold">This is some text in a div element.</div>

The editor returns the following markup.

<p>The sky is <b>blue</b>.</p>
<p><b>This is some text in a div element.</b></p>

Notice that the font-weight:bold formatting is preserved and converted to a b tag since it corresponds to the Bold toolbar button. Color formatting in the markup is removed.

Usage Considerations

Although the toolbar buttons for creating tables and inserting images and links are not available, creating them programmatically or copy and pasting these elements preserves the formatting in the editor. However, resizing of images is not supported.

When using lightning:inputRichText in a standalone app, extend force:slds to display the editor styling correctly.

Methods

This component supports the following method.

focus(): Sets focus on the element.

Attributes

Attribute Name Attribute Type Description Required?
accesskey String Specifies a shortcut key to activate or focus an element.
body Component[] The body of the component. In markup, this is everything in the body of the tag.
class String A CSS class for the outer element, in addition to the component's base classes.
title String Displays tooltip text when the mouse moves over the element.
ariaLabel String Label describing the rich text editor to assistive technologies.
ariaLabelledby String An element ID that provides a label for the rich text editor.
ariaDescribedby String A space-separated list of element IDs that provides descriptive labels for the rich text editor.
disabled Boolean Specifies whether the editor is disabled. This value defaults to false.
disabledCategories List A comma-separated list of button categories to remove from the toolbar.
messageWhenBadInput String Error message that's displayed when valid is false.
onblur Action The action triggered when the element releases focus.
onfocus Action The action triggered when the element receives focus.
placeholder String Text that is displayed when the field is empty.
tabindex Integer Specifies the tab order of an element (when the tab button is used for navigating).
valid Boolean Specifies whether the editor content is valid. If invalid, the slds-has-error class is added. This value defaults to true.
value String The HTML content in the rich text editor.
variant String The variant changes the appearance of the toolbar. Accepted variants include bottom-toolbar.