draftjs-filters
Advanced tools
Filter Draft.js content to preserve only the formatting you allow
Filter Draft.js content to preserve only the formatting you allow. Built for Draftail.
The main use case is to select what formatting to keep when copy-pasting rich text into an editor, for example from Word or Google Docs, addressing Draft.js limitations like #166 and #504. Check out the online demo!
If you want to learn more about how this is used in practice, have a look at Rethinking rich text pipelines with Draft.js.
First, grab the package from npm:
npm install --save draftjs-filters
Then, in your editor import filterEditorState and call it in the Draft.js onChange handler. This function takes two parameters: the filtering configuration, and the editorState.
import { filterEditorState } from "draftjs-filters"
function onChange(nextState) {
const { editorState } = this.state
let filteredState = nextState
const shouldFilterPaste =
nextState.getCurrentContent() !== editorState.getCurrentContent() &&
nextState.getLastChangeType() === "insert-fragment"
if (shouldFilterPaste) {
filteredState = filterEditorState(
{
blocks: ["header-two", "header-three", "unordered-list-item"],
styles: ["BOLD"],
entities: [
{
type: "IMAGE",
attributes: ["src"],
allowlist: {
src: "^http",
},
},
{
type: "LINK",
attributes: ["url"],
},
],
maxNesting: 1,
whitespacedCharacters: ["\n", "\t", "📷"],
},
filteredState,
)
}
this.setState({ editorState: filteredState })
}
Here are all the available options:
// List of allowed block types. unstyled and atomic are always included.
blocks: readonly string[]>,
// List of allowed inline styles.
styles: readonly string[]>,
// List of allowed entities.
entities: readonly []<{
// Entity type, eg. "LINK"
type: string,
// Allowed attributes. Other attributes will be removed. If this is omitted, all attributes are kept.
attributes?: readonly string[]>,
// Refine which entities are kept by matching acceptable values with regular expression patterns.
// It's also possible to use "true" to signify that a field is required to be present,
// and "false" for fields required to be absent.
// If this is omitted, all entities are kept.
allowlist?: {
[attribute: string]: string | boolean,
},
}>,
// Maximum amount of depth for lists (0 = no nesting).
maxNesting: number,
// Characters to replace with whitespace.
whitespacedCharacters: Array<string>,
// Optional: Rules used to automatically convert blocks from one type to another
// based on the block’s text. Also supports setting the block depth.
// Defaults to the filters’ built-in block prefix rules.
blockTextRules?: readonly []<{
// A regex as a string, to match against block text, e.g. "^(◦|o |o\t)".
test: string,
// The type to convert the block to if the test regex matches.
type: string,
// The depth to set (e.g. for list items with different prefixes per depth).
depth: number,
}>,
filterEditorState (and shouldKeepEntityByAttribute described further below) used to support a whitelist config option. It has been renamed to allowlist, and will be removed altogether in a future release.
If your project uses TypeScript, type inference should just work. If you don't use TypeScript, it won't get in your way either.
Flow types were included up to v2.5.0 of the package, and have been removed in v3.0.0.
filterEditorState isn't very flexible. If you want more control over the filtering, simply compose your own filter function with the other single-purpose utilities. The Draft.js filters are published as ES6 modules using Rollup – module bundlers like Rollup and Webpack will tree shake (remove) the unused functions so you only bundle the code you use.
If using filters that remove blocks, be sure to use applyContentWithSelection to restore the selection where appropriate after filtering.
Creates atomic blocks where they would be required for a block-level entity to work correctly, when such an entity exists. Note: at the moment, this is only useful for IMAGE entities that Draft.js injects on arbitrary blocks on paste.
content ContentStateResets atomic blocks to have a single-space char and no styles. This is how they are stored by Draft.js by default.
content ContentStateRemoves atomic blocks for which the entity type isn't allowed.
allowlist readonly {type: string}[]content ContentStateRemoves blocks that have a non-zero depth, and aren't list items.
Happens with Apple Pages inserting unstyled items between list items.
content ContentStateChanges block type and depth based on the block's text. – some word processors add a specific prefix within the text, eg. "· Bulleted list" in Word 2010. Also removes the matched text. This is meant first and foremost for list items where the list bullet or numeral ends up in the text. Other use cases may not be well covered.
Resets the depth of all the content to at most max.
max numbercontent ContentStateConverts all block types not present in the list to unstyled. Also sets depth to 0 (for potentially nested list items).
allowlist readonly string[]content ContentStateRemoves all styles not present in the list.
allowlist readonly string[]content ContentStateClones entities in the entityMap, so each range points to its own entity instance. This only clones entities as necessary – if an entity is only referenced in a single range, it won't be changed.
content ContentStateFilters entity ranges (where entities are applied on text) based on the result of the callback function. Returning true keeps the entity range, false removes it. Draft.js automatically removes entities if they are not applied on any text.
filterFn function (content: ContentState, entityKey: string, block: BlockNode): booleancontent ContentStateKeeps all entity types (images, links, documents, embeds) that are enabled.
Removes invalid images – they should only be in atomic blocks. This only removes the image entity, not the camera emoji (📷) that Draft.js inserts.
Filters entities based on the data they contain.
entityTypes readonly {type: string, allowlist: {}?, whitelist: {}?}[]entityType stringdata { [attr: string]: any }Filters data on an entity to only retain what is allowed. This is crucial for IMAGE and LINK, where Draft.js adds a lot of unneeded attributes (width, height, etc).
Replaces the given characters by their equivalent length of spaces, in all blocks.
characters readonly string[]content ContentStateApplies the new content to the editor state, optionally moving the selection to be on a valid block, inserting one if needed. See https://github.com/thibaudcolas/draftjs-filters/issues/27.
editorState EditorStatecontent ContentStatenextContent ContentStateApplies filtering and preservation operations to the editor content, to restrict it to supported patterns. Will not alter the editor state if there are no changes to make.
options FilterOptionseditorState EditorStateCondenses an array of content blocks into a single block.
This exhibits two known issues:
nextState EditorStateprevState EditorStateThe Draft.js filters only support modern browsers with ES2020 features. Support for legacy browsers can be achieved, up to IE11, by appropriately transpiling the package’s code and including the required Draft.js polyfills.
Have a look at our test data in pasting/.
| Editor - Browser | Chrome Windows | Chrome macOS | Firefox Windows | Firefox macOS | Edge Windows | IE11 Windows | Safari macOS | Safari iOS | Chrome Android |
|---|---|---|---|---|---|---|---|---|---|
| Word 2016 | N/A | N/A | |||||||
| Word 2010 | N/A | N/A | N/A | N/A | N/A | ||||
| Apple Pages | N/A | N/A | N/A | N/A | N/A | ||||
| Google Docs | |||||||||
| Word Online | Unsupported | ? | ? | ||||||
| Dropbox Paper | Unsupported | ? | ? | ||||||
| Draft.js |
Use the Draft.js Cut/Copy/Paste testing plan. We target specific external sources, and have ready-made test documents available to test them:
Here are external sources we want to pay special attention to, and for which we have ready-made test documents with diverse rich content.
There are known Draft.js issues with pasting in IE11. For now, we advise users to turn on stripPastedStyles in IE11 only so that Draft.js removes all formatting but preserves whitespace:
const IS_IE11 = !window.ActiveXObject && "ActiveXObject" in window
const editor = <Editor stripPastedStyles={IS_IE11} />
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.
View the full list of contributors. MIT licensed. Website content available as CC0.
Microsoft Word toolbars screenshot from PCWorld – Microsoft Word Turns 25 article.
FAQs
Filter Draft.js content to preserve only the formatting you allow
The npm package draftjs-filters receives a total of 4,440 weekly downloads. As such, draftjs-filters popularity was classified as popular.
We found that draftjs-filters demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."