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.

Rich text usage

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 option	Mac key command	PC key command	Description
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, ⌘⇧S	Ctrl + Shift + B, Ctrl + Shift + I, Ctrl + Shift + S	Enables 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, ⌥⇧M	Alt + M, Alt + Shift + M	Enables indentation and un-indentation
tables			Allows users to insert a simple table
links	⌘K	Ctrl + K	Allows users to create hyperlinks
images			Allows users to insert images
cut-copy-paste	⌘X, ⌘C, ⌘V	Ctrl + X, Ctrl + C, Ctrl + V	Enables 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.

Markdown usage

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.

Properties

Name	Type	Description
`autoFocus`	`boolean`	Will automatically focus the RTE on render if true
`className`	`string`	Additional CSS classes.
`defaultValue`	`string`	Default value for the RTE - HTML String
`disabled`	`boolean`	Disable 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
`id`	`string`	Sets 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.
`info`	`ReactNode`	It is recommended to pass a simple string to offer guidance. Text will be styled based on status prop.
`label`	`ReactNode`	Pass a string or a fragment with an Icon and string.
`labelHidden`	`boolean`	Visually hides the label region.
`markdownOnly`	`boolean`	Turning on markdown only turns off the tool bar, any rich text features, and input styling
`menu`	`MenuProps`	The menu that will render as a response to a search query.
`name`	`string`	Sets html name attribute for the underlying control. Useful for mapping to a data field.
`onBlur`	`() => void`	A callback that runs if the editor loses focus
`onChange`	`() => void`	A callback that supplies an object with functions that can manipulate the editor and retrieve it's content/state
`onFocus`	`() => void`	A callback that runs if the editor is focused
`onImageAdded`	`(image: File, id: string) => void`	A 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.
`placeholder`	`string`	Standard placeholder for an input
`readOnly`	`boolean`	Makes the input non editable and non clickable. The browser defaults to false.
`ref`	`Ref<RichTextEditorState>`	Handle to the state.
`required`	`boolean`	Indicate if the field is required. The browser defaults to false.
`searchRenderers`	`SearchRenderers[]`	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.
`toolbar`	`Features[]`	An array of strings that activate features on the toolbar
`type`	`'html' \|'markdown'`
`value`	`string`	Creates a controlled input and sets the value. Requires an onChange handler to update value. value + onChange is the recommended method per React team.