Add format buttons

Go back to How to use

RoosterJs is a framework-independnt javascript HTML editor, so it doesn't have any UI component such as format buttons. But it does provide the ability to do format operations. So what you need to do is to build your format bar UI base on any existing UI framework you are using in your project, and call format APIs from roosterJs in the event handlers of your UI components.

Format API

RoosterJs provides more than 20 format APIs to help proceed the format actions. They are living in roosterjs-editor-api package. Here's a list of what we have currently:

clearFormat

Clear the format in current selection, after cleaning, the format will be changed to default format. The format that get cleaned include B/I/U/font name/ font size/text color/background color/align left/align right/align center/superscript/subscript.

createLink

Insert a hyperlink at cursor. When there is a selection, hyperlink will be applied to the selection, otherwise a hyperlink will be inserted to the cursor position.

insertImage

Insert an image to editor at current selection

insertTable

Insert table into editor at current selection

removeLink

Remove link at selection. If no links at selection, do nothing. If selection contains multiple links, all of the link styles will be removed. If only part of a link is selected, the whole link style will be removed.

setAlignment

Set content alignment to left, center or right.

setBackgroundColor

Set background color at current selection

setDirection

Change direction for the blocks/paragraph at selection to either from lef to right, or from right to left.

setFontName

Set font name at selection.

setFontSize

Set font size at selection.

setImageAltText

Set image alt text for all selected images at selection. If no images is contained in selection, do nothing. The alt attribute provides alternative information for an image if a user for some reason cannot view it (because of slow connection, an error in the src attribute, or if the user uses a screen reader).

setIndentation

Set indentation at selection. If selection contains bullet/numbering list, increase/decrease indentation will increase/decrease the list level by one.

setTextColor

Set text color at selection.

toggleBlockQuote

Toggle blockquote at selection, if selection already contains any blockquoted elements, the blockquoted elements will be unblockquoted and other elements will take no affect.

toggleBold

Toggle bold at selection. If selection is collapsed, it will only affect the following input after caret. If selection contains only bold text, the bold style will be removed. If selection contains only normal text, bold style will be added to the whole selected text. If selection contains both bold and normal text, bold stle will be added to the whole selected text.

toggleBullet

Toggle bullet at selection. If selection contains bullet in deep level, toggle bullet will decrease the bullet level by one. If selection contains number list, toggle bullet will convert the number list into bullet list. If selection contains both bullet/numbering and normal text, the behavior is decided by corresponding browser execCommand API.

toggleHeader

Toggle header at selection to be h1, h2, ... , h6 or not a header.

toggleItalic

Toggle italic at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only italic text, the italic style will be removed. If selection contains only normal text, italic style will be added to the whole selected text. If selection contains both italic and normal text, italic stlye will be added to the whole selected text.

toggleNumbering

Toggle numbering at selection. If selection contains numbering in deep level, toggle numbering will decrease the numbering level by one. If selection contains bullet list, toggle numbering will convert the bullet list into number list. If selection contains both bullet/numbering and normal text, the behavior is decided by corresponding realization of browser execCommand API.

toggleStrikethrough

Toggle strikethrough at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only strikethrough text, the strikethrough style will be removed. If selection contains only normal text, strikethrough style will be added to the whole selected text. If selection contains both strikethrough and normal text, strikethrough stlye will be added to the whole selected text.

toggleSubscript

Toggle subscript at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only subscript text, the subscript style will be removed. If selection contains only normal text, subscript style will be added to the whole selected text. If selection contains both subscript and normal text, the subscript style will be removed from whole selected text. If selection contains any superscript text, the behavior is determined by corresponding realization of browser.

toggleSuperscript

Toggle superscript at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only superscript text, the superscript style will be removed. If selection contains only normal text, superscript style will be added to the whole selected text. If selection contains both superscript and normal text, the superscript style will be removed from whole selected text. If selection contains any subscript text, the behavior is determined by corresponding realization of browser execCommand API.

toggleUnderline

Toggle underline at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only underlined text, the underline style will be removed. If selection contains only normal text, underline style will be added to the whole selected text. If selection contains both underlined and normal text, the underline style will be added to the whole selected text.

Undo and Redo

Undo and Redo are very popular button in format bar. Their correlated APIs are not in roosterjs-editor-api package, but they are member function of Editor class directly. You can call editor.undo() and editor.redo() to perform these actions.

Example

Suppose we have below HTML code to build the format bar with 3 basic buttons: bold, italic, underline:

<div>
    <button id="bold"><b>B</b></button>
    <button id="italic"><i>I</i></button>
    <button id="underline"><u>U</u></button>
</div>

Then use the following javascript code to handle click event of these buttons. (rooster.js file is directly used in this example. Please reference to the first example in Preparation)

document.getElementById('bold').addEventListener('click', function() {
    roosterjs.toggleBold(editor);
});
document.getElementById('italic').addEventListener('click', function() {
    roosterjs.toggleItalic(editor);
});
document.getElementById('underline').addEventListener('click', function() {
    roosterjs.toggleUnderline(editor);
});

To add more buttons, you need to render more UI buttons and call the format APIs above.

RoosterJs-react example

roosterjs-react repository contains a react based roosterjs wrapper and some UI components including a format bar (a.k.a Ribbon). You can check out source code, compile and run its sample site to see how a Ribbon and other UI components are created based on react and roosterjs.