@trejgun/mui-rte v0.0.14

mui-rte

The Material-UI Rich Text Editor and Viewer

mui-rte is a complete text editor and viewer for material-ui based on draft-js and written in Typescript. It is ready to use out of the box yet supports user defined blocks, styles, autocomplete strategies, async/sync custom atomic blocks, callbacks, and decorators as well as toolbar and theme customization to enhance the editor to all needs.

Installation

npm install mui-rte --save

Install the peer dependencies: @material-ui/core, @material-ui/icons, react and react-dom.

Demo

Usage

import MUIRichTextEditor from 'mui-rte'

ReactDOM.render(
    <MUIRichTextEditor label="Start typing..." />,
    document.getElementById("root")
)

You can load default content as the following example. The value should be a stringified RawDraftContentState object:

import MUIRichTextEditor from 'mui-rte'

const data = getContentStateAsStringFromSomewhere()

ReactDOM.render(
    <MUIRichTextEditor
        defaultValue={data}
        label="Start typing..."
    />,
    document.getElementById("root")
)

Examples

Check the examples directory for more.

Custom Controls

You can define your custom inline styles, blocks, atomic blocks and callback actions to the editor. Just select an icon from @material-ui/icons or create your own FunctionComponent and define your rules.

Adding a custom inline style

This sample adds a control to change the background color and font color of the typed or selected text:

import MUIRichTextEditor from 'mui-rte'
import InvertColorsIcon from '@material-ui/icons/InvertColors'

<MUIRichTextEditor
    controls={["my-style"]}
    customControls={[
        {
            name: "my-style",
            icon: <InvertColorsIcon />,
            type: "inline",
            inlineStyle: {
                backgroundColor: "black",
                color: "white"
            }
        }
    ]}
/>

Adding a custom block

This sample adds a block to the editor based on a React Element:

import MUIRichTextEditor from 'mui-rte'
import TableChartIcon from '@material-ui/icons/TableChart'

const MyBlock: FC = props => {
    const {children} = props;
    return (
        <div style={{
            padding: 10,
            backgroundColor: "#ebebeb"
        }}>
            My Block content is:
            {children}
        </div>
    )
}

<MUIRichTextEditor
    controls={["my-block"]}
    customControls={[
        {
            name: "my-block",
            icon: <TableChartIcon />,
            type: "block",
            blockWrapper: <MyBlock />
        }
    ]}
/>

Adding a custom atomic block (Async)

It is possible to insert custom blocks based on asynchronous behavior using the insertAtomicBlockAsync API. The above example shows an example on how to upload an image and use the MUIRichTextEditor default image control for further edition. You can use this behavior to upload a file when dropping it inside the editor and render it as an image entity after upload.

Check this other sample that shows how to add a @material-ui/core Card with asynchronous downloaded content.

Adding a custom atomic block (Sync)

Check this sample that shows how to create a control to add a @material-ui/core Card component to the editor.

Adding a custom callback control

This sample adds a control that will trigger a custom callback function to clear the editor state:

import MUIRichTextEditor from 'mui-rte'
import DoneIcon from '@material-ui/icons/Done'
import { EditorState } from 'draft-js'

<MUIRichTextEditor
    controls={["my-callback"]}
    customControls={[
        {
            name: "my-callback",
            icon: <DoneIcon />,
            type: "callback",
            onClick: (editorState, name, anchor) => {
                console.log(`Clicked ${name} control`)
                return EditorState.createEmpty()
            }
        }
    ]}
/>

Autocomplete strategies

You can define autocomplete strategies to present suggested content lists based on the text input. Just set your trigger character, add some search keys and the content to insert and the editor will do everything for you. You can navigate through suggestions using the keyboard arrows and finally press 'Enter' to insert your content into the editor.

Simple strategy example

This is an example to show emoji suggestions when the user start typing a text like ':face', ':joy', or ':grin':

import MUIRichTextEditor from 'mui-rte'

const emojis = [
    {
        keys: ["face", "grin"],
        value: "😀",
        content: "😀",
    },
    {
        keys: ["face", "joy"],
        value: "😂",
        content: "😂",
    },
    {
        keys: ["face", "sweat"],
        value: "😅",
        content: "😅",
    }
]

<MUIRichTextEditor
    autocomplete={{
        strategies: [
            {
                items: emojis,
                triggerChar: ":"
            }
        ]
    }}
/>

Check this sample that shows how to add multiple autocomplete strategies to a single editor.

Atomic strategy example

Check this sample that shows how to combine atomic custom controls with the autocomplete strategy feature.

Custom Decorators

You can define custom decorators to apply styles and/or functionality based on a provided regular expression.

Adding custom functionality with a decorator

To add some functionality when a user inputs a #hashtag use the following example. In this case, everytime the user inputs a word starting with a # character it will be automatically converted into a styled link:

import MUIRichTextEditor from 'mui-rte'

const MyHashTagDecorator: FC = props => {
  const {decoratedText, children} = props;
    const hashtagUrl = `http://myurl/${decoratedText}`
    return (
        <a
            href={hashtagUrl}
            style={{
                color: "green"
            }}
        >
            {children}
        </a>
    )
}

<MUIRichTextEditor
    label="Type something here..."
    decorators={[
        {
            component: MyHashTagDecorator,
            regex: /\#[\w]+/g
        }
    ]}
/>

Inline toolbar

The editor includes an inline toolbar option which renders a pop-up inside the editor area when the user makes a selection. The inline toolbar supports user defined controls. Notice that only inline type controls will be rendered. The controls displayed on the main toolbar can be different from the ones in the inline toolbar. You can also hide the main toolbar and just enable the inline toolbar.

import MUIRichTextEditor from 'mui-rte'

<MUIRichTextEditor
    label="Type something here..."
    inlineToolbar={true}
/>

Styling the editor

You can style the editor using the Material-UI theming feature. First create a theme with createMuiTheme and override classes such as root, container, editor, and editorContainer. Check the examples directory for more.

import { createMuiTheme, MuiThemeProvider } from '@material-ui/core'
import MUIRichTextEditor from 'mui-rte'

const defaultTheme = createMuiTheme()

Object.assign(defaultTheme, {
    overrides: {
        MUIRichTextEditor: {
            root: {
                marginTop: 20,
                width: "80%"
            },
            editor: {
                borderBottom: "1px solid gray"
            }
        }
    }
})

<MuiThemeProvider theme={defaultTheme}>
    <MUIRichTextEditor
        label="Type something here..."
    />
</MuiThemeProvider>

API

<MUIRichTextEditor /> (IMUIRichTextEditorProps)

TCustomControl

TToolbarComponentProps

TDecorator

TKeyCommand

TDraftEditorProps

TAutocomplete

TAutocompleteStrategy

TAutocompleteItem

TMUIRichTextEditorRef

TAsyncAtomicBlockResponse

Changelog

Check the release notes for the changelog.

Development

For development use:

$ npm run watch
$ npm run serve

Future plans

• Increase test coverage
• Refactor code
• Add new features

Suggestions and issues

Please feel free to leave your comment on the Issues tab.

License

Licensed under MIT License.