Rich Text Toolbar Button

The lightning-rich-text-toolbar-button component creates a button for the toolbar for lightning-input-rich-text.

Place lightning-rich-text-toolbar-button inside the lightning-rich-text-toolbar-button-group component, which groups the custom buttons.

You can include multiple button groups, and each group can contain multiple buttons.

For more information about custom button groups, see lightning-rich-text-toolbar-button-group documentation.

Use the icon-name attribute to specify a Lightning Design System utility icon to display on the button.

Use icon-alternative-text to describe the button’s function for users of assistive technologies.

The selected attribute reflects the state of the button. Specify selected in the lightning-rich-text-toolbar-button component to indicate when the button is selected, and the button background color is dark. By default, selected is false and the button background color is light.

Specify the disabled attribute to display the button icon as light gray and prevent the button from being selected.

Use lightning-rich-text-toolbar-button within lightning-input-rich-text, which implements the rich text editor blueprint in the Salesforce Lightning Design System (SLDS). The rich text editor adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

You can create buttons by using the lightning-rich-text-toolbar-button component attributes and the onclick handler to perform an action. For example, you can create a handler to format text, insert text, attach a file to a feed post, or open a popup.

For information about formatting or inserting text programmatically, see the lightning-input-rich-text documentation.

This example includes one button group that contains one button for applying code-block format. The code-block format isn’t a default format in lightning-input-rich-text, so the formats attribute specifies all the formats required in the toolbar.

1<template>
2    <lightning-input-rich-text
3        formats="font, bold, italic, underline, strike,
4    list, indent, align, link, image, clean, code, code-block, color, background, header"
5    >
6        <lightning-rich-text-toolbar-button-group
7            slot="toolbar"
8            aria-label="First group"
9        >
10            <lightning-rich-text-toolbar-button
11                icon-name="utility:insert_tag_field"
12                icon-alternative-text="Code Snippet"
13                onclick={handleCodeBlockButtonClick}
14            >
15            </lightning-rich-text-toolbar-button>
16        </lightning-rich-text-toolbar-button-group>
17    </lightning-input-rich-text>
18</template>

The handler gets the format currently set in the editor, and applies or removes the code-block format, depending on the current format.

1import { LightningElement } from "lwc";
2
3export default class CustomButtonDemo extends LightningElement {
4  handleCodeBlockButtonClick() {
5    const inputRichText = this.template.querySelector("lightning-input-rich-text");
6    let format = inputRichText.getFormat();
7
8    // Set or unset code-block format based on format on current selection
9    if (format["code-block"]) {
10      inputRichText.setFormat({ "code-block": false });
11    } else {
12      inputRichText.setFormat({ "code-block": true });
13    }
14  }
15}

The lightning-rich-text-toolbar-button component provides methods that enable you to open and close popups from custom buttons.

Use the showPopup() method to open a popup from a custom button, and use closePopup() to close it.

Provide the content of the popup by nesting components inside lightning-rich-text-toolbar-button.

Popups close by default if you click outside the popup. The popupclickout event fires when you click outside, so you can use a handler on this event to prevent closing if needed.

This example creates a Save button that opens a popup to prompt the user to save the content. The popup content consists of a text input field and two buttons. The Save custom button prevents the default clickout behavior.

To indicate to assistive technologies that the button can open an interactive dialog, specify aria-haspopup="dialog".

1<template>
2    <lightning-input-rich-text>
3        <lightning-rich-text-toolbar-button-group
4            slot="toolbar"
5            aria-label="First group"
6        >
7            <lightning-rich-text-toolbar-button
8                icon-name="utility:save"
9                icon-alternative-text="Save"
10                onclick={openPopup}
11                onpopupclickout={handlePopupClickout}
12                aria-haspopup="dialog"
13            >
14                <!-- Popup Items -->
15                <lightning-input label="Save As"></lightning-input>
16                <div class="slds-m-top_small">
17                    <lightning-button
18                        variant="brand"
19                        label="Save"
20                        onclick={handleSave}
21                    >
22                    </lightning-button>
23                    <lightning-button
24                        variant="bare"
25                        label="Cancel"
26                        onclick={closePopup}
27                        style="margin-left: .25rem"
28                    >
29                    </lightning-button>
30                </div>
31            </lightning-rich-text-toolbar-button>
32            <lightning-rich-text-toolbar-button
33                icon-name="utility:brush"
34                disabled
35            ></lightning-rich-text-toolbar-button>
36        </lightning-rich-text-toolbar-button-group>
37
38        <lightning-rich-text-toolbar-button-group
39            slot="toolbar"
40            aria-label="Second group"
41        >
42            <lightning-rich-text-toolbar-button
43                icon-name="utility:email"
44            ></lightning-rich-text-toolbar-button>
45            <lightning-rich-text-toolbar-button
46                icon-name="utility:call"
47            ></lightning-rich-text-toolbar-button>
48        </lightning-rich-text-toolbar-button-group>
49    </lightning-input-rich-text>
50</template>

The JavaScript simply calls showPopup() to create the popup. The component handles the positioning and styling of the popup for you.

The example’s handlePopupClickout function calls event.preventDefault() to prevent the popup from closing. The user can only close it by clicking the popup’s Save or Cancel buttons, or by pressing the Escape key.

1import { LightningElement } from "lwc";
2
3export default class CustomButtonPopupDemo extends LightningElement {
4  preventCloseOnClickOut = true;
5
6  openPopup(event) {
7    event.target.showPopup();
8  }
9
10  closePopup() {
11    this.template.querySelectorAll("lightning-rich-text-toolbar-button")[0].closePopup();
12  }
13
14  handleSave() {
15    const name = this.template.querySelector("lightning-input");
16    this.enteredText = name.value;
17    // save the content
18    this.closePopup();
19  }
20
21  handlePopupClickout(event) {
22    if (this.preventCloseOnClickOut) {
23      event.preventDefault();
24    }
25  }
26}

Use icon-alternative-text to describe the button’s function. The text is assigned to the title attribute for the button tooltip. The text is also used as assistive text for users of assistive technologies.

Use aria-haspopup to indicate the availability and type of interactive popup element on a toggle button. See MDN web docs: aria-haspopup.

When a toolbar button is clicked once, the aria-pressed attribute is appended with a value of true, which tells assistive technologies that a button is in a pressed state. The button remains in the pressed state until it’s clicked another time, which changes the value back to false. For example, the bold formatting button is a toggle button that either applies or removes bold formatting on selected text. The button turns blue when clicked once and aria-pressed is true. When the button is clicked another time, the blue background on the button is removed and aria-pressed is false.

Toolbar buttons that open a dialog use aria-haspoup and not aria-pressed as they aren’t toggle buttons.

popupclickout

The event fired when a popup is open and you click outside it.

The popupclickout event returns no parameters.

The event properties are as follows.