Ricos API

Ricos Common API

children

children?: RichContentEditor | RichContentViewer

For backward compatibility. Any prop given to the child component will deeply override the matching prop created in Ricos' internal logic. Read more about backward compatibility in Migrating from rich-content

<RicosEditor>

<RichContentEditor placeholder={'Type here!'} />

</RicosEditor>

content

content?: DraftContent

A DraftContent is an immutable object that saves the entire content created by a RicosEditor. For RicosViewer this is a requirement, it will set the content to display. For the RicosEditor this will set its initial state.

cssOverride

cssOverride?: RicosCssOverride

CSS class overriding that will be passed to RichContentEditor or RichContentViewer.

<RicosEditor

cssOverride={{

modalTheme: {

content: { zIndex: 1 },

overlay: { width: '100%' },

},

}}

/>

note

Works similarly to the theme property of RichContentEditor and RichContentViewer.

warning

This API is deprecated in RCE@Next (aka Tiptap based Editor)

isMobile

isMobile?: boolean

Will render in mobile optimized mode

linkSettings

relValue is Deprecated , please use rel instead.

CustomAnchorScroll: (event: Event, anchor: string) => void;

linkSettings?: {

anchorTarget?: string;

relValue?: string;

rel?: { nofollow?: boolean; sponsored?: boolean; ugc?: boolean; noreferrer?: boolean };

customAnchorScroll?: CustomAnchorScroll;

}

Defines the behavior of links. anchorTarget - as defined in HTMLAnchorElement.target relValue - as defined in HTMLAnchorElement.rel customAnchorScroll - enables overriding the default anchor scroll behavior

Examples:

1. Links created by the User:

linkSettings: {

anchorTarget: '_blank',

rel: { nofollow: false, sponsored: false, ugc: false, noreferrer: true },

}

2. Links created by UoU:

linkSettings: {

anchorTarget: '_blank',

rel: { nofollow: true, sponsored: false, ugc: true, noreferrer: true},

}

locale

locale?: string

Any two letter string representing a supported locale. Determines the language and text direction of modals and settings.

localeContent

localeContent?: string

Only needed when locale of content is different from UI locale. If not defined locale prop will be used. Any two letter string representing a supported locale. Determines the language and text direction of content.

mediaSettings

When changing fullscreen's background and foreground colors, make sure to choose colors that aren't too similar.
default colors are:
backgroundColor: 'white'; foregroundColor: 'black';
The string values should be css color strings (e.g 'black', '#2F2E2E', etc)

mediaSettings?: {

pauseMedia?: boolean;

disableDownload?: boolean;

fullscreenProps?: {

backgroundColor?: string;

foregroundColor?: string;

}

}

pauseMedia

When true, media like videos will be paused. A possible use case is for pausing videos on tab switch.

disableRightClick (deprecated)

Disables the mouse right click functionality for the gallery, video and image plugins.

disableDownload

Sets the initial value of disableDownload for image, gallery and video plugins. Images - disables right click. Gallery - disables right click. Video - removes the download option from context menu.

onError

onError?: (error: string) => void

TODO

plugins

plugins?: PluginConfig[]

For every plugin you install, import it and add it to the plugins array.

import { RicosEditor } from 'ricos-editor';

import { pluginVideo } from 'wix-rich-content-plugin-video';

<RicosEditor plugins={[pluginVideo()]} />;

note

For rendering a viewer, import the plugin from the viewer entry point
wix-rich-content-plugin-video/viewer

theme

Adding theme to Ricos is possible with providing a RicosTheme object. Further read in Theming page.

iframeSandboxDomain

In order for the UGC source code to be rendered in an isolated environment, iframeSandboxDomain config on viewer & editor must be supplied, and be easily changed by consumer in case of DDOS on domain or subdomain

textWrap

textWrap?: boolean;

When a plugin is aligned left/right, text will be next to the plugin (image, galleries, and etc).

Default value:

textWrap: true;

Ricos Editor API

keyboardShortcuts

Customizable keyboard shortcut for Return API, currently limited to Enter-related shortcuts. Allows to remap new line / soft new line editor functionalities to Enter-based combination, or to remap Enter key to custom action.

keyboardShortcuts?: [{

name: 'NewLine' | 'SoftNewLine' | 'Enter';

description: string;

group: 'ShortcutsSheet_Section_Formatting';

keys: {

macOs: 'Shift+Enter' | 'Enter' | 'Meta+Enter' | 'Ctrl+Enter';

windows: 'Shift+Enter' | 'Enter' | 'Meta+Enter' | 'Ctrl+Enter';

};

command: (commands: EditorCommands, modalService: ModalService) => void;

enabled: boolean;

}]

name

Enter-related shortcut name

description

Free text description, displayed in Shortcuts Sheet help dialog

keys

Platform-dependent key combination (common combination: { macOs: 'Shift+Enter', windows: 'Shift+Enter' }, { macOs: 'Enter', windows: 'Enter' }, { macOs: 'Meta+Enter', windows: 'Ctrl+Enter' })

command

Command triggered by shortcut

enabled

Enables the shortcut

Example:

import type { CustomizableKeyboardShortcut } from 'ricos-types';

keyboardShortcuts: CustomizableKeyboardShortcut[] = [

{

name: 'NewLine',

description: 'Remap new line editor functionality to Shift+Enter',

keys: { macOs: 'Shift+Enter', windows: 'Shift+Enter' },

command: editorCommands => editorCommands.newLine()

}, {

name: 'Enter',

description: 'Remap Enter key to custom action',

keys: { macOs: 'Enter', windows: 'Enter' },

command: () => submitForm(); // user defined action

}, {

name: 'SoftNewLine',

description: 'Remap new line editor functionality to Ctrl+Enter',

keys: { macOs: 'Meta+Enter', windows: 'Ctrl+Enter' },

command: editorCommands => editorCommands.softNewLine()

}

];

rceNext

rceNext?: true | false;

rceNext: true allows you to enjoy the new Editor. Please be aware, this is a temporary api!, it will be removed when Draft editor is fully deprecated.

schemaType

schemaType?: 'Draft' | 'RichContent';

schemaType prop, sets the schema type of the Editor, default value is Draft. schemaType: 'RichContent' is used for deprecating Draft Editor, it should be used with rceNext: true. Please be aware, this is a temporary api!, it will be removed when Draft editor is fully deprecated.

draftEditorSettings?: {

autoCapitalize?: string;

autoComplete?: string;

autoCorrect?: string;

spellCheck?: boolean;

stripPastedStyles?: boolean;

handleBeforeInput?: ((chars: string, editorState: EditorState, eventTimeStamp: number) => 'handled' | 'not-handled');

handlePastedText?: ((text: string, html: string, editorState: EditorState) => 'handled' | 'not-handled');

handleReturn?: ((e: SyntheticKeyboardEvent, editorState: EditorState) => 'handled' | 'not-handled');

tabIndex?: string;

}

draft-js props, as described in https://draftjs.org/docs/api-reference-editor

injectedContent

injectedContent?: DraftContent

Similar to content prop; allows content to be injected to mounted RicosEditor without need for remount.

linkPanelSettings

linkPanelSettings?: {

showNewTabCheckbox?: boolean;

showNoFollowCheckbox?: boolean;

showSponsoredCheckbox?: boolean;

showNoReferrerCheckbox?: boolean;

placeholder?: string;

externalPopups?: boolean;

}

Settings for the link panel component.

showNewTabCheckbox

Determines the 'Open link in a new tab' link panel checkbox visibility. By default, it's visible.

showNoFollowCheckbox

Determines the 'Add a nofollow tag' link panel checkbox visibility. By default, it's visible.

showSponsoredCheckbox

Determines the 'Mark as a sponsored link' link panel checkbox visibility. By default, it's hidden.

showNoReferrerCheckbox

Determines the 'Add a noreferrer tag' link panel checkbox visibility. By default, it's visible.

blankTargetToggleVisibilityFn

Deprecated , please use showNewTabCheckbox instead.

Determines the 'Open link in a new tab' link panel checkbox visibility. By default, it's visible.

nofollowRelToggleVisibilityFn

Deprecated , please use showNoFollowCheckbox instead.

Determines the 'Add a nofollow tag' link panel checkbox visibility. By default, it's visible.

placeholder

Determines the placeholder to use for the link panel. By default, its value is "Enter a URL here" translated by localization

externalPopups

Determines the position of the link modal. Passing true places the link modal on the topmost layer. By default, this value is false.

Examples:

1. Links created by the User:

linkPanelSettings: {

showNewTabCheckbox: true;

showNoFollowCheckbox: true;

showSponsoredCheckbox: true;

showNoReferrerCheckbox: true;

}

2. Links created by UoU:

linkPanelSettings: {

showNewTabCheckbox: false;

showNoFollowCheckbox: false;

showSponsoredCheckbox: false;

showNoReferrerCheckbox: false;

}

maxTextLength

Limits the editor text length to a given value. When the max text length is reached, further text input is ignored. Also, text paste action is canceled if the resulting text would exceed the max length.

modalSettings

Customize the ReactModal of RicosEditor, or alternatively provide callbacks to create your own Modal.

modalSettings?: {

ariaHiddenId?: string;

openModal?: (modalProps: object) => void;

closeModal?: () => void;

container?: HTMLElement;

}

container

When used, container will be the target of Ricos editor modal (using ReactDOM.createPortal)

ariaHiddenId

Accessibility prop. Provides aria-hidden attribute to a given DOM Element ID while the modal is open, making it hidden for screenreaders of users. Passed directly into the ReactModal's AppElement.

Default Value: body

<RicosEditor modalSettings={{ ariaHiddenId: '#root' }} />

openModal & closeModal

Legacy RCE's openModal, closeModal (helpers)[rce_api/helpers].

note

Leave these empty if you don't plan to use a Modal Component of your own. Otherwise, RicosEditor will assume you do, and won't handle the ReactModal it's supplied with.

onBusyChange

onBusyChange?: (isBusy: boolean) => void

A function that will be called with true when the editor is busy, e.g. when a media plugin begins uploading, and will be called with false when the editor becomes idle again.

onChange

onChange?: (content: DraftContent) => void

A callback that runs whenever the editor's content is edited.

placeholder

placeholder?: string

This text will appear in the editor until content is created

<RicosEditor placeholder={'The placeholder appears until you start typing'} />

The placeholder appears until you start typing

ref

ref?: React.Ref

A react Ref. Use this to access editor functions.

Function	Description
focus(): void	Focuses the editor
blur(): void	Blurs the editor
getContent(): DraftContent	Retrieves current content
getContentPromise(options: { flush?: boolean; publishId?: string}): Promise<DraftContent>	Retrieves current content promise
getContentTraits(): { isEmpty: boolean; isContentChanged: boolean; isLastChangeEdit: boolean}	Retrieves current content traits
getToolbarProps(options: { type: ToolbarType }): { buttons: ToolbarButtonProps[] }	button props for external toolbar

Usage example:

class MyComponent extends React.Component {

componentDidMount() {

this.editor.focus();

}

render() {

<RicosEditor ref={editor => (this.editor = editor)} />;

}

}

ref.getContentPromise

Returns (promise) of the Content Data (DraftContent type). publishId - used for BI (onPublish event), set it when called before publishing a an editor's content in your app. flush - trigger blur of the editor to force changes (such as composition mode in android) before getting the content

toolbarSettings

toolbarSettings?: {

getToolbarSettings?: GetToolbarSettings;

textToolbarContainer?: HTMLElement;

useStaticTextToolbar?: boolean;

}

getToolbarSettings

The getToolbarSettings API allows to config toolbar appearance and behavior.

Built-in editor and plugin toolbars customization

Toolbar Customization

External toolbar customization

Sometimes, the built-in toolbar customization is insufficient. The toolbar externalization API comes to solve these cases. It allows users to implement custom toolbars and buttons, providing all the required button props, e.g. onClick callback, button icon, label, tooltip, etc.

The getToolbarSettings API allows to configure external toolbars as well. Since external toolbar could be used both for plugin insertion and text formatting, these roles are configured separately. Once the external toolbars are configured, the button props could be retrieved by the editor ref method getToolbarProps.

Insert plugin toolbar

The plugin insertion toolbar configuration object should contain the name: TOOLBARS.INSERT_PLUGIN field. By default, the shouldCreate returns false for all the platforms, so it is crucial to override it for button props activation. The getButtons is expected to return an array of INSERT_PLUGIN_BUTTONS enum values. The default list of the insert plugin button names is passed to the getToolbarSettings via the pluginButtonNames argument field.

Formatting toolbar

The formatting toolbar configuration object should contain the name: TOOLBARS.FORMATTING field. By default, the shouldCreate returns false for all the platforms, so it is crucial to override it for button props activation. The getButtons is expected to return an array of FORMATTING_BUTTONS enum values. The default list of the button names is passed to the getToolbarSettings via the textButtons argument field.

textToolbarContainer

Given some container HTML element, the text toolbar will be rendered inside it. Overrides useStaticTextToolbar.

const RicosWithToolbarContainer = () => {

const bottomToolbar = document.createElement('div');

useEffect(() => {

const wrappingDiv = document.getElementById('editor-static-toolbar-wrapper');

wrappingDiv.appendChild(bottomToolbar);

}, []);

return (

<div id="editor-static-toolbar-wrapper">

<RicosEditor toolbarSettings={{ textToolbarContainer: bottomToolbar }} />

</div>

);

};

In this example we render the static text toolbar below the editor.

useStaticTextToolbar

The text toolbar appears inline when selecting some text and allows styling text. Set to true in order to render the text toolbar in a fixed position above the editor.

Hi there! I'm Ricos, your rich content framework. 👾

sideBlockComponent

sideBlockComponent?: FC<{id:string}>

When given, component will be placed on the side of every block.

Ricos Viewer API

preview

warning

This API exists for backward compatibility, and on its way to deprecation. Please use Content API instead.

preview?: {

transformation?: ContentStateTransformation;

contentInteractionMappers?: Function;

onPreviewExpand?: () => void;

}

A preview decoration for RicosViewer. Read more in Preview

seoSettings

seoSettings?: boolean | {

paywall: {

className: string;

index: number;

};

}

When given a truthy value, renders RicosViewer in a SEO optimized mode. An object allows extended configuration.

paywall

className - Content blocked by a payall will be marked up using this string (This class will be used by Googlebot to discern between paid and free content on a page level) index - number of free content blocks

addAnchors

TODO

textSelectionToolbar

When given a truthy value, text-selection-toolbar appears inline when selecting some text and allows tweet text.

import { RicosViewer } from 'ricos-viewer';

<RicosViewer textSelectionToolbar />;

Select some text below to see text-selection-toolbar

Hi there! I'm Ricos, your rich content framework. 👾