{"id":13683225,"url":"https://github.com/niuware/mui-rte","last_synced_at":"2025-04-30T12:33:56.397Z","repository":{"id":34932578,"uuid":"191712255","full_name":"niuware/mui-rte","owner":"niuware","description":"Material-UI Rich Text Editor and Viewer","archived":false,"fork":false,"pushed_at":"2024-02-14T18:52:22.000Z","size":657,"stargazers_count":442,"open_issues_count":100,"forks_count":168,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-28T21:47:02.525Z","etag":null,"topics":["draft-js","material-ui","mui","react","rich-text-editor","rte","text-editor","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niuware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-13T07:22:48.000Z","updated_at":"2025-04-24T06:00:46.000Z","dependencies_parsed_at":"2024-06-17T06:01:16.370Z","dependency_job_id":"1b12ac09-b611-487a-9bcb-3e35296671c0","html_url":"https://github.com/niuware/mui-rte","commit_stats":{"total_commits":151,"total_committers":6,"mean_commits":"25.166666666666668","dds":0.3841059602649006,"last_synced_commit":"aacd718237b542096cc30a91c4b4011701287443"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niuware%2Fmui-rte","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niuware%2Fmui-rte/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niuware%2Fmui-rte/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niuware%2Fmui-rte/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niuware","download_url":"https://codeload.github.com/niuware/mui-rte/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251644829,"owners_count":21620631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["draft-js","material-ui","mui","react","rich-text-editor","rte","text-editor","typescript"],"created_at":"2024-08-02T13:02:04.628Z","updated_at":"2025-04-30T12:33:55.874Z","avatar_url":"https://github.com/niuware.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# mui-rte  \n\nThe Material-UI Rich Text Editor and Viewer\n\n\u003cimg src=\"https://raw.githubusercontent.com/niuware/niuware.github.io/master/public/assets/mui-rte/editor-1-9-0.png\" width=\"600\" /\u003e\n\n**mui-rte** is a complete text editor and viewer for the MUI library (formerly 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.\n\n## Installation\n\n```\nnpm install mui-rte --save\n```\n\nInstall the peer dependencies: `@mui/material`, `@mui/icons-material`, `@mui/styles`, `react` and `react-dom`. Also you will need to install the peer dependencies for MUI: `@emotion/react` and `@emotion/styled`.\n\n## Demo\n\n[![Edit mui-rte basic](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/mui-rte-basic-ypfdo?fontsize=14)\n\n## Usage\n\n```js\nimport { createTheme, ThemeProvider } from '@mui/material/styles'\nimport MUIRichTextEditor from 'mui-rte'\n\nconst myTheme = createTheme({\n    // Set up your custom MUI theme here\n})\n\nReactDOM.render(\n    \u003cThemeProvider theme={myTheme}\u003e\n        \u003cMUIRichTextEditor label=\"Start typing...\" /\u003e\n    \u003c/ThemeProvider\u003e, \n    document.getElementById(\"root\")\n)\n```\n\nYou can load default content as the following example. The value should be a stringified `RawDraftContentState` object:\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\n\nconst data = getContentStateAsStringFromSomewhere()\n\nReactDOM.render(\n    \u003cThemeProvider theme={myTheme}\u003e\n        \u003cMUIRichTextEditor \n            defaultValue={data}\n            label=\"Start typing...\" \n        /\u003e\n    \u003c/ThemeProvider\u003e, \n    document.getElementById(\"root\")\n)\n```\n\n## Material-UI v4 compatibility\n\n`mui-rte` version 2.x is compatible with MUI (v5) only. You can still use version [1.x](https://github.com/niuware/mui-rte/releases/tag/1.29.0) for Material-UI v4. Current code using `mui-rte` version 1.x should be compatible with version 2.x, the only breaking change is that it requires to be wrapped on a `ThemeProvider` as shown in the examples.\n\n## Examples\n\nCheck the [examples](https://github.com/niuware/mui-rte/tree/master/examples) directory for more. \n\n## Custom Controls\n\nYou can define your custom inline styles, blocks, atomic blocks and callback actions to the editor. Just select an icon from `@mui/icons-material` or create your own `FunctionComponent` and define your rules.\n\n### Adding a custom inline style\n\nThis sample adds a control to change the background color and font color of the typed or selected text:\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\nimport InvertColorsIcon from '@mui/icons-material/InvertColors'\n\n\u003cMUIRichTextEditor \n    controls={[\"my-style\"]}\n    customControls={[\n        {\n            name: \"my-style\",\n            icon: \u003cInvertColorsIcon /\u003e,\n            type: \"inline\",\n            inlineStyle: {\n                backgroundColor: \"black\",\n                color: \"white\"\n            }\n        }\n    ]}\n/\u003e\n```\n\n### Adding a custom block\n\nThis sample adds a block to the editor based on a `React Element`:\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\nimport TableChartIcon from '@mui/icons-material/TableChart'\n\nconst MyBlock = (props) =\u003e {\n    return (\n        \u003cdiv style={{\n            padding: 10,\n            backgroundColor: \"#ebebeb\"\n        }}\u003e\n            My Block content is:\n            {props.children}\n        \u003c/div\u003e\n    )\n}\n\n\u003cMUIRichTextEditor \n    controls={[\"my-block\"]}\n    customControls={[\n        {\n            name: \"my-block\",\n            icon: \u003cTableChartIcon /\u003e,\n            type: \"block\",\n            blockWrapper: \u003cMyBlock /\u003e\n        }\n    ]}\n/\u003e\n```\n\n### Adding a custom atomic block (Async)\n\n\u003cimg src=\"https://raw.githubusercontent.com/niuware/niuware.github.io/master/public/assets/mui-rte/async-upload-demo.gif\" width=\"600\" /\u003e\n\nIt is possible to insert custom blocks based on asynchronous behavior using the `insertAtomicBlockAsync` API. The above example shows an [example](https://github.com/niuware/mui-rte/blob/master/examples/async-image-upload/index.tsx) 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.\n\nCheck this [other sample](https://github.com/niuware/mui-rte/blob/master/examples/async-atomic-custom-block/index.tsx) that shows how to add a `@mui/material` Card with asynchronous downloaded content.\n\n### Adding a custom atomic block (Sync)\n\nCheck [this sample](https://github.com/niuware/mui-rte/blob/master/examples/atomic-custom-block/index.tsx) that shows how to create a control to add a `@mui/material` Card component to the editor.\n\n### Adding a custom callback control\n\nThis sample adds a control that will trigger a custom callback function to clear the editor state:\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\nimport DoneIcon from '@mui/icons-material/Done'\nimport { EditorState } from 'draft-js'\n\n\u003cMUIRichTextEditor \n    controls={[\"my-callback\"]}\n    customControls={[\n        {\n            name: \"my-callback\",\n            icon: \u003cDoneIcon /\u003e,\n            type: \"callback\",\n            onClick: (editorState, name, anchor) =\u003e {\n                console.log(`Clicked ${name} control`)\n                return EditorState.createEmpty()\n            }\n        }\n    ]}\n/\u003e\n```\n\n## Autocomplete strategies\n\n\u003cimg src=\"https://raw.githubusercontent.com/niuware/niuware.github.io/master/public/assets/mui-rte/ac-demo.gif\" width=\"600\" /\u003e\n\nYou 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.\n\n### Simple strategy example\n\nThis is an example to show emoji suggestions when the user start typing a text like ':face', ':joy', or ':grin':\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\n\nconst emojis = [\n    {\n        keys: [\"face\", \"grin\"],\n        value: \"😀\",\n        content: \"😀\",\n    },\n    {\n        keys: [\"face\", \"joy\"],\n        value: \"😂\",\n        content: \"😂\",\n    },\n    {\n        keys: [\"face\", \"sweat\"],\n        value: \"😅\",\n        content: \"😅\",\n    }\n]\n\n\u003cMUIRichTextEditor \n    autocomplete={{\n        strategies: [\n            {\n                items: emojis,\n                triggerChar: \":\"\n            }\n        ]\n    }}\n/\u003e\n```\n\nCheck [this sample](https://github.com/niuware/mui-rte/blob/master/examples/autocomplete/index.tsx) that shows how to add multiple autocomplete strategies to a single editor.\n\n### Atomic strategy example\n\nCheck [this sample](https://github.com/niuware/mui-rte/blob/master/examples/autocomplete/index.tsx) that shows how to combine atomic custom controls with the autocomplete strategy feature.\n\n## Custom Decorators\n\nYou can define custom decorators to apply styles and/or functionality based on a provided regular expression. \n\n### Adding custom functionality with a decorator\n\nTo 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:\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\n\nconst MyHashTagDecorator = (props) =\u003e {\n    const hashtagUrl = \"http://myurl/\" + props.decoratedText\n    return (\n        \u003ca \n            href={hashtagUrl}\n            style={{\n                color: \"green\"\n            }}\n        \u003e\n            {props.children}\n        \u003c/a\u003e\n    )\n}\n\n\u003cMUIRichTextEditor \n    label=\"Type something here...\"\n    decorators={[\n        {\n            component: MyHashTagDecorator,\n            regex: /\\#[\\w]+/g\n        }\n    ]}\n/\u003e\n```\n\n## Inline toolbar\n\nThe 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.\n\n```js\nimport MUIRichTextEditor from 'mui-rte'\n\n\u003cMUIRichTextEditor \n    label=\"Type something here...\"\n    inlineToolbar={true}\n/\u003e\n```\n\n## Styling the editor\n\nYou 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.\n\n```js\nimport { createMuiTheme, MuiThemeProvider } from '@mui/material/styles'\nimport MUIRichTextEditor from 'mui-rte'\n\nconst defaultTheme = createMuiTheme()\n\nObject.assign(defaultTheme, {\n    overrides: {\n        MUIRichTextEditor: {\n            root: {\n                marginTop: 20,\n                width: \"80%\"\n            },\n            editor: {\n                borderBottom: \"1px solid gray\" \n            }\n        }\n    }\n})\n\n\u003cMuiThemeProvider theme={defaultTheme}\u003e\n    \u003cMUIRichTextEditor \n        label=\"Type something here...\"\n    /\u003e\n\u003c/MuiThemeProvider\u003e\n```\n\n## API\n\n`\u003cMUIRichTextEditor /\u003e (TMUIRichTextEditorProps)`\n\n|Property|Type||description|\n|---|---|---|---|\n|id|`string`|optional|Base Id name for the component HTML elements.|\n|ref|`TMUIRichTextEditorRef`|optional|Sets a reference instance of the editor component.|\n|label|`string`|optional|String to show when there is no content.|\n|readOnly|`boolean`|optional|Read only mode. The toolbar is disabled by default.|\n|value|`string`|deprecated|Use `defaultValue` instead.|\n|defaultValue|`string`|optional|Default content to load. Should be a stringified `Draft.Model.Encoding.RawDraftContentState` object.|\n|inheritFontSize|`boolean`|optional|Inherit font size from parent. Useful for read only mode.|\n|error|`boolean`|optional|Renders the editor with an error style.|\n|controls|`string[]`|optional|List of controls to display in the main toolbar. If not provided, all controls will be rendered. Current available values are: \"title\", \"bold\", \"italic\", \"underline\", \"strikethrough\", \"highlight\", \"undo\", \"redo\", \"link\", \"media\", \"numberList\", \"bulletList\", \"quote\", \"code\", \"clear\", \"save\".|\n|customControls|`TCustomControl[]`|optional|Defines an array of user custom inline styles, blocks and callbacks. See more information in 'Custom Controls' below.|\n|decorators|`TDecorator[]`|optional|Defines an array of user custom decorators. See more information in 'Custom Decorators'.|\n|toolbar|`boolean`|optional|Defines if the main toolbar should be rendered.|\n|toolbarButtonSize|`small` \\| `medium`|optional|Sets the size on the default `IconButton` component for the main toolbar.|\n|inlineToolbar|`boolean`|optional|Defines if the inline toolbar should be rendered.|\n|inlineToolbarControls|`string[]`|optional|List of controls to display in the inline toolbar. Available values are: \"bold\", \"italic\", \"underline\", \"strikethrough\", \"highlight\", \"link\", \"clear\", and user defined inline controls. If not provided and `inlineToolbar` is `true` the following inline styles will be displayed: bold, italic, underline and clear.|\n|keyCommands|`TKeyCommand[]`|optional|Defines an array of `TKeyCommand` objects for adding key bindings to the editor.|\n|draftEditorProps|`TDraftEditorProps`|optional|Defines an object containing specific `draft-js` `Editor` properties.|\n|maxLength|`number`|optional|Sets the maximum characters count that can be input into the editor.|\n|autocomplete|`TAutocomplete`|optional|Sets autocomplete strategies to present suggestion lists as the user types into the editor.|\n|onSave|`(data:string) =\u003e void`|optional|Function triggered when the save button is pressed. The `data` is a stringified `Draft.Model.Encoding.RawDraftContentState` object.|\n|onChange|`(state: EditorState) =\u003e void`|optional|Function triggered on any change in the editor (key input, delete, etc.). The `state` is a `Draft.Model.ImmutableData.EditorState` object.|\n|onFocus|`() =\u003e void`|optional|Function triggered when when the editor acquires focus.|\n|onBlur|`() =\u003e void`|optional|Function triggered when when the editor loses focus.|\n\n\u003cbr /\u003e\n\n`TCustomControl`\n\n|Property|Type||description|\n|---|---|---|---|\n|id|`string`|optional|The HTML id attribute for the control|\n|name|`string`|required|The name of the custom control. For rendering the control this name should be added to the `MUIRichTextEditor` `controls` property.|\n|icon|`JSX.Element`|optional|The `@mui/icons-material` icon for the control. For \"atomic\" control type, the icon is not required. [Check this](https://material.io/resources/icons/?style=baseline) for available icons.|\n|component|`React.FunctionComponent\u003cTToolbarComponentProps\u003e`|optional|The custom function component for the control. The icon has priority over the component, so if the icon is set the component will be ignored. For \"atomic\" control type, the component is not required.|\n|type|`string`|required|Either \"inline\", \"block\", \"atomic\" or \"callback\"|\n|inlineStyle|`string`|optional|The `React.CSSProperties` object for styling the text when using a custom inline style.|\n|blockWrapper|`React.ReactElement`|optional|The custom React component used for rendering a custom block.|\n|atomicComponent|`React.FunctionComponent`|optional|The custom React FunctionComponent used for rendering a custom atomic block.|\n|onClick|`(editorState: EditorState, name: string, anchor: HTMLElement \\| null) =\u003e EditorState \\| void`|optional|The callback function triggered when the custom control is clicked. The received arguments include the current `EditorState` object, the name of the clicked control and the `HTMLElement` from which the click was raised. If a new `EditorState` object is returned it will be replace the current one in the editor (useful to explicitly modify the `EditorState`).|   \n\n\u003cbr /\u003e\n\n`TToolbarComponentProps`  \n\n|Property|Type|description|  \n|---|---|---|  \n|id|`string`|The id for the component.|\n|onMouseDown|`(e: React.MouseEvent) =\u003e void`|The `mousedown` handler.|\n|active|`boolean`|Defines if the block or inline type is active for the current editor selection.|\n|disabled|`boolean`|Sets if the toolbar is disabled.|   \n\n\u003cbr /\u003e\n\n`TDecorator`\n\n|Property|Type||description|\n|---|---|---|---|\n|component|`React.FunctionComponent`|required|The React component to use for rendering the decorator.|\n|regex|`RegExp`|required|The regular expression to match a decorator.|  \n\n\u003cbr /\u003e\n\n`TKeyCommand`\n\n|Property|Type||description|\n|---|---|---|---|\n|key|`number`|required|The code of the key to bind.|\n|name|`string`|required|The name of the command.|\n|callback|`(state: EditorState) =\u003e EditorState`|required|The callback function to execute when the key binding is matched. It should return the `EditorState` to set.|   \n\n\u003cbr /\u003e\n\n`TDraftEditorProps`\n\n|Property|Type||description|\n|---|---|---|---|\n|spellCheck|`boolean`|optional|Use browser spelling check.|\n|stripPastedStyles|`boolean`|optional|Remove styles when pasting text into the editor.|  \n|handleDroppedFiles|`(selectionState: SelectionState, files: Blob[]) =\u003e DraftHandleValue`|optional|Handle files that have been dropped into the editor. The `DraftHandleValue` is either `handled` or `not-handled`.|   \n\n\u003cbr /\u003e\n\n`TAutocomplete`\n\n|Property|Type||description|\n|---|---|---|---|\n|strategies|`TAutocompleteStrategy[]`|required|Array of autocomplete strategies.|\n|suggestLimit|`number`|optional|Defines the amount of suggestions to present to the user. Default is `5`.|   \n\n\u003cbr /\u003e\n\n`TAutocompleteStrategy`\n\n|Property|Type||description|\n|---|---|---|---|\n|triggerChar|`string`|required|A single character that triggers the autocomplete strategy.|\n|items|`TAutocompleteItem[]`|required|List of autocomplete suggestion items.| \n|insertSpaceAfter|`boolean`|optional|If `false` it won't add an space after inserting the content into the editor. Default is `true`.|   \n|atomicBlockName|`string`|optional|Use an *atomic* custom control type to add the content to the editor.|   \n\n\u003cbr /\u003e\n\n`TAutocompleteItem`\n\n|Property|Type||description|\n|---|---|---|---|\n|keys|`string[]`|required|The list of keys that the user needs to type to reveal this item suggestion.|\n|value|`any`|required|The value to insert into the editor when the item is selected.|\n|content|`string \\| JSX.Element`|required|The content presented in the autocomplete suggestion list for this item. Note that this content is render under a `ListItem` component.|   \n\n\u003cbr /\u003e\n\n`TMUIRichTextEditorRef`\n\n|Property|Type||description|\n|---|---|---|---|\n|focus|`() =\u003e void`||Triggers the focus event on the editor.|\n|save|`() =\u003e void`||Triggers the save method on the editor.|\n|insertAtomicBlock|`(name: string, data: any)`|deprecated|Use `insertAtomicBlockSync` instead.|\n|insertAtomicBlockSync|`(name: string, data: any)`||Inserts an atomic block named as `name` (if exists) with the provided `data` into the editor.|\n|insertAtomicBlockAsync|`(name: string, promise: Promise\u003cTAsyncAtomicBlockResponse\u003e, placeholder?: string) =\u003e void`||Inserts an atomic block named as `name` (if exists) asynchronously with the provided `data` into the editor. The `placeholder` text will be shown on the editor until the promise is resolved.|   \n\n\u003cbr /\u003e   \n\n`TAsyncAtomicBlockResponse`\n\n|Property|Type||description|\n|---|---|---|---|\n|data|`any`|required|The data assigned to the entity added into the editor.|    \n\n\u003cbr /\u003e   \n\n## Changelog\n\nCheck the [release notes](https://github.com/niuware/mui-rte/releases) for the changelog.\n\n## Development \n\nFor development use:\n\n```\n$ npm run build\n$ npm run serve\n```\n\n## Future plans\n\n- Add test coverage\n- Refactor code\n- Add new features\n\n## Suggestions and issues\n\nPlease feel free to leave your comment on the [Issues](https://github.com/niuware/mui-rte/issues) tab.\n\n## License\n\nLicensed under MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniuware%2Fmui-rte","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniuware%2Fmui-rte","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniuware%2Fmui-rte/lists"}