📝✨ Little Draft.js helpers to make rich text editors just work. Built for Draftail.
Check out the online demo!
Features
Infinite list nesting
By default, Draft.js only provides support for 5 list levels for bulleted and numbered lists. While this is often more than enough, some editors need to go further.
Instead of manually writing and maintaining the list nesting styles, use those little helpers:
import { getListNestingStyles, blockDepthStyleFn } from "draftjs-conductor";
<style>
{getListNestingStyles(6)}
</style>
<Editor blockStyleFn={blockDepthStyleFn} />
getListNestingStyles
will generate the necessary CSS for your editor’s lists. blockDepthStyleFn
will then apply classes to blocks based on their depth, so the styles take effect. Voilà!
If your editor’s maximum list nesting depth never changes, pre-render the styles as a fragment for better performance:
const listNestingStyles = <style>{getListNestingStyles(6)}</style>;
You can also leverage React.memo
to speed up re-renders even if max
was to change:
const NestingStyles = React.memo(ListNestingStyles);
<style>
<NestingStyles max={max} />
</style>;
Relevant Draft.js issues:
Idempotent copy-paste between editors
The default Draft.js copy-paste handlers lose a lot of the formatting when copy-pasting between Draft.js editors. While this might be ok for some use cases, sites with multiple editors on the same page need them to reliably support copy-paste.
Relevant Draft.js issues:
All of those problems can be fixed with this library, which overrides the copy
and cut
events to transfer more of the editor’s content, and introduces a function to use with the Draft.js handlePastedText
to retrieve the pasted content.
This will paste all copied content, even if the target editor might not support it. To ensure only supported content is retained, use filters like draftjs-filters.
Note: IE11 isn’t supported, as it doesn't support storing HTML in the clipboard, and we also use the Element.closest
API.
With draft.js 0.11 and above
Here’s how to use the copy/cut override, and the paste handler:
import {
onDraftEditorCopy,
onDraftEditorCut,
handleDraftEditorPastedText,
} from "draftjs-conductor";
class MyEditor extends Component {
constructor(props: Props) {
super(props);
this.state = {
editorState: EditorState.createEmpty(),
};
this.onChange = this.onChange.bind(this);
this.handlePastedText = this.handlePastedText.bind(this);
}
onChange(nextState: EditorState) {
this.setState({ editorState: nextState });
}
handlePastedText(
text: string,
html: string | null,
editorState: EditorState,
) {
let newState = handleDraftEditorPastedText(html, editorState);
if (newState) {
this.onChange(newState);
return true;
}
return false;
}
render() {
const { editorState } = this.state;
return (
<Editor
editorState={editorState}
onChange={this.onChange}
onCopy={onDraftEditorCopy}
onCut={onDraftEditorCut}
handlePastedText={this.handlePastedText}
/>
);
}
}
The copy/cut event handlers will ensure the clipboard contains a full representation of the Draft.js content state on copy/cut, while handleDraftEditorPastedText
retrieves Draft.js content state from the clipboard. Voilà! This also changes the HTML clipboard content to be more semantic, with less styles copied to other word processors/editors.
You can also use getDraftEditorPastedContent
method and set new EditorState by yourself. It is useful when you need to do some transformation with content (for example filtering unsupported styles), before past it in the state.
With draft.js 0.10
The above code relies on the onCopy
and onCut
event handlers, only available from Draft.js v0.11.0 onwards. For Draft.js v0.10.5, use registerCopySource
instead, providing a ref
to the editor:
import {
registerCopySource,
handleDraftEditorPastedText,
} from "draftjs-conductor";
class MyEditor extends Component {
componentDidMount() {
this.copySource = registerCopySource(this.editorRef);
}
componentWillUnmount() {
if (this.copySource) {
this.copySource.unregister();
}
}
render() {
const { editorState } = this.state;
return (
<Editor
ref={(ref) => {
this.editorRef = ref;
}}
editorState={editorState}
onChange={this.onChange}
handlePastedText={this.handlePastedText}
/>
);
}
}
With draft-js-plugins
The setup is slightly different with draft-js-plugins
(and React hooks) – we need to use the provided getEditorRef
method:
const editor = useRef<Editor>(null);
useEffect(() => {
let unregisterCopySource: undefined | unregisterObject = undefined;
if (editor.current !== null) {
unregisterCopySource = registerCopySource(
editor.current.getEditorRef() as any,
);
}
return () => {
unregisterCopySource?.unregister();
};
});
See #115 for further details.
Editor state data conversion helpers
Draft.js has its own data conversion helpers, convertFromRaw
and convertToRaw
, which work really well, but aren’t providing that good of an API when initialising or persisting the content of an editor.
We provide two helper methods to simplify the initialisation and serialisation of content. createEditorStateFromRaw
combines EditorState.createWithContent
, EditorState.createEmpty
and convertFromRaw
as a single method:
import { createEditorStateFromRaw } from "draftjs-conductor";
const editorState = createEditorStateFromRaw(null);
const editorState = createEditorStateFromRaw({ entityMap: {}, blocks: [] });
const editorState = createEditorStateFromRaw(null, decorator);
To save content, serialiseEditorStateToRaw
combines convertToRaw
with checks for empty content – so empty content is saved as null
, rather than a single text block with empty text as would be the case otherwise.
import { serialiseEditorStateToRaw } from "draftjs-conductor";
const content = serialiseEditorStateToRaw(editorState);
Contributing
See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our contribution guidelines.
Credits
View the full list of contributors. MIT licensed. Website content available as CC0. Image credit: FirefoxEmoji.