Skip to main content
Table of Contents

Rich-text editor

A rich-text editor lets a user edit and format text using a “what-you-see-is-what-you-get” (WYSIWYG) editing area.

Table of Contents
Rich-text editor

Anatomy

A Rich-text editor (RTE) can be used for writing various things such as articles, comments, and messages. The toolbar has menus and actions for controlling the appearance of text. It can also be a shortcut for adding content such as images, links, and other types of media.

Toolbar actions are designed to look and behave like Icon buttons. They should follow Icon buttons as much as possible including focus and hover states.

Rich-text editor
  1. Media button
  2. Media button with hidden labels
  3. Toggle icon button
  4. Icon button
  5. Menu

For the content inside the rich-text editor, the visual treatment should follow the defined typography styles in the toolbar.

Rich-text editor

Related components

Toolbar sections

Toolbar sections have semantic meaning, so it’s important that they’re categorized by function. Toolbar can have up to 4 categories that are visually separated and appear in this order.

Toolbar sections
  1. Text formatting
  2. Paragraph formatting
  3. Insert media
  4. Other actions

Toolbars with only a few actions can have them grouped together without separators.

Collapsed toolbar sections

Text formatting

  • Text style (Dropdown selections: Paragraph, Heading 1, Heading 2, Heading 3)
  • Text size (Dropdown selections: Small, Normal, Large, Extra large)
  • Text color (Dropdown selection: Color swatch)
  • Bold
  • Italic
  • Underline

Paragraph formatting

  • Code
  • Bulleted list
  • Numbered list
  • Increase indent
  • Decrease indent
  • Alignment (Dropdown selections: Left, Center, Right)

Insert media

  • Blockquote
  • Link
  • Horizontal Rule
  • Code block
  • Image
  • Video
  • Table

Other actions

  • HTML Source Editing
  • Emoji

Tooltips

Tooltips should be provided for every action, unless the action contains a label (for example Paragraph), following Icon button best practices.

Formatting

Toolbar location

When considering the placement of the toolbar, think about the size of the editing experience. For long-form writing, anchor the toolbar to the top of the editor.

Rich-text editor with the toolbar on the top

For short-form writing, the toolbar can also be anchored to the bottom of the editor.

Rich-text editor with the toolbar on the bottom

Display the toolbar in a menu when space is limited. When using a menu, provide at least 20px padding within the textarea to prevent toolbars from covering content.

Rich-text editor with the hidden toolbar as a menu that can be opened Rich-text editor with the opened toolbar as a menu

Toolbar size

Default size of the toolbar is 48px. This includes icon buttons with 8px padding in the toolbar. Compact version of the toolbar reduces the padding to 4px with the height of the toolbar being 40px tall. The compact version is better suited when there are certain space constraints, such as being used in a Drawer.

Examples of default and compact toolbar sizes
  1. Default size toolbar with 8px padding
  2. Compact size toolbar 4px padding

Responsive behavior

Toolbar actions are responsive based on the width of the container. Icons can be used while keeping the chevron to show that there are dropdown selections.

Paragraph dropdown example where the icon replaces the label if the space is limited
  1. Media button
  2. Media button with hidden label

When a toolbar has many actions, the actions at the end will go into an overflow menu.

Overflow menu is visible if toolbar actions can't fit all the icons

Resizable textarea

Textarea should resize vertically as the user types. The minimum and maximum height can be restricted depending on space constraints.

Rich-text editor with minimum height of the textarea defined Rich-text editor height expands with additional content

Once the maximum height of the textarea is reached, a scrollbar should appear next to it.

Scrollbar visible on the side once the textarea reaches its maximum height

States

Disabled states

If a formatting option is not available for selected text, it should be disabled.

Disabled icon button example
  1. Disabled icon button

Flows

Inserting new link

New link can be added by selecting a text and converting it to a link with a shortcut or by pressing the button.

Selecting text to create a link Creating a new link from selected text

Editing link

Editing link tooltip dialog should give the user a choice of previewing the link and opening it in a new window, editing the link or breaking the link.

Previewing the link in the rich-text editor Editing the link in the rich-text editor

Localization

CKEditor offers user interface localization options and the translation system is opened to third-party plugins. Read more about it on the CKEditor localization support page.

Accessibility

Managing focus

When the toolbar is opened as a menu, the focus should be looped within that menu. This should be the case for all dropdowns in the toolbar.

Focus order when opening a floating toolbar
  1. User selects the text they want to make bold
  2. Pressing tab will take them to the toolbar unless Tab key is reserved for indenting. In that case, a custom shortcut is used to move the focus to the toolbar.
  3. The focus is then inside the toolbar until they pick an action or close the toolbar with the Esc key. If textarea reserves the use of Tab key for indenting lines, the user can use the Left arrow and Right arrow to navigate within the toolbar.
  4. Once the toolbar is closed, the focus goes back to its original position

If the editor has enabled indentation, the Tab key will be reserved for setting the indentation of the current line. In those situations a custom text shortcut is used to move the focus from the editor to the toolbar: Alt + F10 on PC, and Option + F10 on macOS. Read more about keyboard support.

Feedback

Help improve this page. Give us your feedback