RichTextEditor

The RichTextEditor is capable of collecting free-form text and images from the user and also allows the text to be styled. It can be used within a Form when styled text is preferred over the plain text provided by the TextArea component. It allows for styling such as bold, italics, and strikethrough text, hyperlink creation, font sizing, indentation, list creation, and the insertion of Tables and Links.

The RichTextEditor generates a variety of outputs on request such as plain text, rich text, and html. These values are best displayed via the RichTextViewer component. The RichTextEditor component also allows for standard Form field structures such as being set required, disabled, or readOnly, as well as including a label, status, or info.

For more information on how to use the features and props for this component, check out the developer documentation.

The RichTextEditor component will by default render as an HTML-powered TextArea with additional support for styling text and inserting other rich features. It may also render as markdown input only. Both variations include callback functions for onChange, onFocus, and onBlur, as well as a placeholder and defaultValue. You may also adjust the min and max height of the input region.

Toolbar

When the RichTextEditor is in HTML mode, you may pass an array of allowable options to the toolbar prop. Every option you pass will be included in the toolbar at the bottom of the input. Users may interact with these options to directly modify styling of the selected text, or insert other elements into the input. Most of the options have associated key commands for quick use.

Toolbar optionMac key commandPC key commandDescription
headers⌘⌥{0|1|2|3|4}Ctrl + Alt + {0|1|2|3|4}Allows users to select between normal text and four levels of headings
inline-styling⌘⇧B, ⌘⇧I, ⌘⇧SCtrl + Shift + B, Ctrl + Shift + I, Ctrl + Shift + SEnables bold, italics, and strikethrough styling
lists⌘⇧L (Unordered list only)Ctrl + Shift + L (Unordered list only)Allows users to insert ordered and unordered lists
indentation⌥M, ⌥⇧MAlt + M, Alt + Shift + MEnables indentation and un-indentation
tablesAllows users to insert a simple table
links⌘KCtrl + KAllows users to create hyperlinks
imagesAllows users to insert images
cut-copy-paste⌘X, ⌘C, ⌘VCtrl + X, Ctrl + C, Ctrl + VEnables cut, copy, and paste functionality

State functions

The RichTextEditor uses a React Imperative Handle in order to update its ref with new functions that allow you to interact with the RichTextEditor programmatically. By passing a React ref to the component's ref prop, you can access the functions from that ref's current object. These functions include focus, clear, appendImage, insertText, and insertHtml. You can also leverage functions to return the value of the RichTextEditor input in various formats. These functions include getPlainText, getRichText, and getHtml.

The RichTextEditor can be formatted for markdown input by passing the markdownOnly prop. In this mode, the following markdown syntax is fully supported: headings, bold, italics, strikethrough, lists, links, and images. Check out this documentation for more information on markdown syntax.

Search and replace

In markdown mode, the RichTextEditor can accept a set of searchTriggers, which are objects containing a trigger character and regex to validate the text following the trigger. The RichTextEditor will validate user input and if the input matches a given searchTrigger, the onSearch callback function will be triggered. This function will pass as parameters the search query and the trigger that initiated the search.

When a search occurs, you may pass Menu attributes to the menu prop on the RichTextEditor. This will render a Menu over the search query within the input. When a user selects an item from the Menu, that selection's id will be passed to an onSearchItemReplacement callback function. If this function is provided to the component, it can be used to determine how to render the chosen search result within the input.

The search functionality is a crucial feature for the Cosmos Feed component, but it may also be leveraged for custom use. In the demo below, try initiating a search with the @ trigger.

NameTypeDefaultDescription
autoFocusbooleanWill automatically focus the RTE on render if true
classNamestringAdditional CSS classes.
defaultValuestringDefault value for the RTE - HTML String
disabledbooleanDisable the control. The browser defaults to false.
getSearchItemReplacement
(id: string) => {
  component: ComponentType<any>;
  markdown: undefined | string;
  props: Record<string, any>;
  text: string;
} | undefined
Callback triggered on selection of a search result that returns an object representing the node to replace the search with.
height
string | {
  max: string;
  min: undefined | string;
}
Sets the height for the RTE. If no max height is set the RTE will continue to expand, otherwise an overflow will be applied
idstringSets DOM id for the control and associates label element via 'for' attribute. If an id is not pass, a random id will be generated for any render.
infoReactNodeIt is recommended to pass a simple string to offer guidance. Text will be styled based on status prop.
labelReactNodePass a string or a fragment with an Icon and string.
labelHiddenbooleanVisually hides the label region.
markdownOnlybooleanTurning on markdown only turns off the tool bar, any rich text features, and input styling
menuMenuPropsThe menu that will render as a response to a search query.
namestringSets html name attribute for the underlying control. Useful for mapping to a data field.
onBlur() => voidA callback that runs if the editor loses focus
onChange() => voidA callback that supplies an object with functions that can manipulate the editor and retrieve it's content/state
onFocus() => voidA callback that runs if the editor is focused
onImageAdded(image: File, id: string) => voidA callback when an image is added through the toolbar image feature
onSearch
(event: {
  search: string;
  trigger: string;
}) => void
Callback triggered on text change following a valid search trigger.
placeholderstringStandard placeholder for an input
readOnlybooleanMakes the input non editable and non clickable. The browser defaults to false.
refRef<RichTextEditorState>Handle to the state.
requiredbooleanIndicate if the field is required. The browser defaults to false.
searchRenderersSearchRenderers[]A set of custom renderer configurations to convert markdown for search results.
searchTriggers
{
  regex: string;
  trigger: string;
}[]
A set of characters that designate special search capabilities.
status
'success' |'warning' |'error' 
Set visual state based on a validation state.
toolbarFeatures[]An array of strings that activate features on the toolbar
type
'html' |'markdown' 
valuestringCreates a controlled input and sets the value. Requires an onChange handler to update value. value + onChange is the recommended method per React team.