---
schema_version: "1"
id: 94e3ba20824f3aba323d5e65c20420655e7d423fc68ceff67ceb3439955510fc
title: Rich Text Toolbar Button
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/richTextToolbarButton/lightning-rich-text-toolbar-button.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 991bffbc4b47f855a48d4c05087564aecd4210c393a95186f988886f791e4711
products:
  - Lightning Component Reference
---
# Rich Text Toolbar Button

**`lightning-rich-text-toolbar-button`**

A custom button on the lightning-input-rich-text toolbar.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

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`](/docs/platform/lightning-component-reference/guide/lightning-rich-text-toolbar-button.html)
documentation.

Use the `icon-name` attribute to specify a Lightning Design System
[utility icon](https://v1.lightningdesignsystem.com/icons/#utility)
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.

## Design

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.

|                | SLDS 1                                                                                                      | SLDS 2                                                                                                          |
| :------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Rich Text Editor](https://v1.lightningdesignsystem.com/components/rich-text-editor)                        | [Rich Text Editor](https://www.lightningdesignsystem.com/components/rich-text-editor/)                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create Custom Buttons

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`](/docs/platform/lightning-component-reference/guide/lightning-input-rich-text.html)
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.

![Rich text editor with a custom toolbar button](https://developer.salesforce.com/media/components/rich-text-toolbar-button.gif '{"class": "image-md", "title": "Rich Text Editor with Custom Toolbar Button"}')

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text
        formats="font, bold, italic, underline, strike,
    list, indent, align, link, image, clean, code, code-block, color, background, header"
    >
        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="First group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:insert_tag_field"
                icon-alternative-text="Code Snippet"
                onclick={handleCodeBlockButtonClick}
            >
            </lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

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

```javascript
import { LightningElement } from "lwc";

export default class CustomButtonDemo extends LightningElement {
  handleCodeBlockButtonClick() {
    const inputRichText = this.template.querySelector("lightning-input-rich-text");
    let format = inputRichText.getFormat();

    // Set or unset code-block format based on format on current selection
    if (format["code-block"]) {
      inputRichText.setFormat({ "code-block": false });
    } else {
      inputRichText.setFormat({ "code-block": true });
    }
  }
}
```

## Open Popups with Custom Buttons (Beta)

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"`.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input-rich-text>
        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="First group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:save"
                icon-alternative-text="Save"
                onclick={openPopup}
                onpopupclickout={handlePopupClickout}
                aria-haspopup="dialog"
            >
                <!-- Popup Items -->
                <lightning-input label="Save As"></lightning-input>
                <div class="slds-m-top_small">
                    <lightning-button
                        variant="brand"
                        label="Save"
                        onclick={handleSave}
                    >
                    </lightning-button>
                    <lightning-button
                        variant="bare"
                        label="Cancel"
                        onclick={closePopup}
                        style="margin-left: .25rem"
                    >
                    </lightning-button>
                </div>
            </lightning-rich-text-toolbar-button>
            <lightning-rich-text-toolbar-button
                icon-name="utility:brush"
                disabled
            ></lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>

        <lightning-rich-text-toolbar-button-group
            slot="toolbar"
            aria-label="Second group"
        >
            <lightning-rich-text-toolbar-button
                icon-name="utility:email"
            ></lightning-rich-text-toolbar-button>
            <lightning-rich-text-toolbar-button
                icon-name="utility:call"
            ></lightning-rich-text-toolbar-button>
        </lightning-rich-text-toolbar-button-group>
    </lightning-input-rich-text>
</template>
```
<!-- prettier-ignore-end -->

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.

```javascript
import { LightningElement } from "lwc";

export default class CustomButtonPopupDemo extends LightningElement {
  preventCloseOnClickOut = true;

  openPopup(event) {
    event.target.showPopup();
  }

  closePopup() {
    this.template.querySelectorAll("lightning-rich-text-toolbar-button")[0].closePopup();
  }

  handleSave() {
    const name = this.template.querySelector("lightning-input");
    this.enteredText = name.value;
    // save the content
    this.closePopup();
  }

  handlePopupClickout(event) {
    if (this.preventCloseOnClickOut) {
      event.preventDefault();
    }
  }
}
```

## Accessibility

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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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.

## Custom Events

**`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.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |


:::::

:::::tab
::component-specification{component="richTextToolbarButton" model="lwc" namespace="lightning"}

:::::

::::::