Draftail

https://www.draftail.org/
Admin
Draftail is a configurable rich text editor built with Draft.js that enables keyboard-driven,...
Tokens:28,884
Snippets:349
Trust Score:8.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Draftail and Dependencies

Source: https://www.draftail.org/docs/introduction/getting-started

Install the required packages via npm.

```bash
npm install --save draftail draft-js@0.10.5 react react-dom
```

--------------------------------

### Install Draftail, Draft.js, and React

Source: https://www.draftail.org/docs/getting-started

Use npm to install the necessary packages for Draftail, Draft.js, and React.

```bash
npm install --save draftail draft-js@0.10.5 react react-dom  

```

--------------------------------

### Draft.js Raw Content Example

Source: https://www.draftail.org/docs/guides/importing-and-exporting-html

This is an example of Draft.js raw content, which can be used with `convertFromRaw` for HTML conversion.

```json
{
  "blocks": [
    {
      "key": "c4oqn",
      "text": "",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Import and Initialize DraftailEditor

Source: https://www.draftail.org/docs/reference/api

Import the DraftailEditor component and render it. This is the basic setup for using Draftail.

```javascript
import { DraftailEditor } from "draftail"
  
const editor = <DraftailEditor />  

```

--------------------------------

### Draftail Editor State Example

Source: https://www.draftail.org/docs/reference/customising-toolbars

Example of editor state containing text and a code block.

```json
{
  "blocks": [
    {
      "key": "5hqv4",
      "text": "Sometimes #hashtags are useful.",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    },
    {
      "key": "53d3m",
      "text": "console.log('Hello, World!');",
      "type": "code-block",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Draftail Editor State for Custom Toolbar

Source: https://www.draftail.org/docs/reference/customising-toolbars

Example of editor state representing a configuration using a custom toolbar.

```json
{
  "blocks": [
    {
      "key": "e35tq",
      "text": "Use custom toolbars for more flexibility.",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Integrate Draftail with Formik

Source: https://www.draftail.org/docs/guides/form-validation

Full example demonstrating how to use Formik to validate Draftail content, including block count and entity requirements.

```javascript
<Formik  
  initialValues={{ content: null }}  
  onSubmit={window.alert.bind(null, "Success!")}  
  validate={(values) => {  
    const errors = {}  
  
    if (!values.content) {  
      errors.content = "Please enter at least two paragraphs"  
    } else {  
      const { blocks, entityMap } = values.content  
      if (Object.keys(entityMap).length === 0) {  
        errors.content = "Please use at least one link"  
      }  
  
      // Check there are at least two blocks with non-whitespace text  
      if (blocks.filter((b) => b.text.trim().length > 0).length < 2) {  
        errors.content = "Please enter at least two paragraphs"  
      }  
    }  
  
    return errors  
  }}  
>  
  {({ errors, touched, handleSubmit, setFieldTouched, setFieldValue }) => (  
    <form onSubmit={handleSubmit}>  
      <div className="form-field">  
        <DraftailEditor  
          entityTypes={[ENTITY_CONTROL.LINK]}  
          onSave={setFieldValue.bind(null, "content")}  
          onBlur={setFieldTouched.bind(null, "content")}  
          stateSaveInterval={errors.content ? 50 : 250}  
        />  
        <div role="alert">  
          {errors.content && touched.content && errors.content}  
        </div>  
      </div>  
      <button type="submit">Submit</button>  
    </form>  
  )}  
</Formik>  

```

--------------------------------

### Example Action List Plugin Data

Source: https://www.draftail.org/docs/introduction/plugins

This JSON represents the content structure for an editor supporting action lists, indicating a custom block type and inline code styling.

```json
{
  "blocks": [
    {
      "key": "aaa",
      "text": "This editor supports action lists. Start one with - [] at the start of a line.",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [
        {
          "offset": 50,
          "length": 4,
          "style": "CODE"
        }
      ],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Draft.js Content State JSON

Source: https://www.draftail.org/examples

Example of a serialized Draft.js content state including custom blocks, inline styles, and entities.

```json
{
  "blocks": [
    {
      "key": "c1gc9",
      "text": "You can implement custom block types as required, and inline styles too, or entities.",
      "type": "tiny-text",
      "depth": 0,
      "inlineStyleRanges": [
        {
          "offset": 37,
          "length": 11,
          "style": "COLOR_D30A64"
        },
        {
          "offset": 54,
          "length": 13,
          "style": "REDACTED"
        }
      ],
      "entityRanges": [
        {
          "offset": 76,
          "length": 8,
          "key": 0
        }
      ],
      "data": {}
    },
    {
      "key": "7dtlg",
      "text": "Draftail also supports the #plugins architecture of draft-js-plugins.",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [
        {
          "offset": 52,
          "length": 16,
          "style": "BOLD"
        }
      ],
      "entityRanges": [],
      "data": {}
    },
    {
      "key": "affm4",
      "text": " ",
      "type": "atomic",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [
        {
          "offset": 0,
          "length": 1,
          "key": 1
        }
      ],
      "data": {}
    },
    {
      "key": "2uo5o",
      "text": ".media .img {",
      "type": "code-block",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    },
    {
      "key": "9cgaa",
      "text": "    margin-inline-end: 10px;",
      "type": "code-block",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    },
    {
      "key": "3dhtn",
      "text": "}",
      "type": "code-block",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {
    "0": {
      "type": "DOCUMENT",
      "mutability": "MUTABLE",
      "data": {
        "url": "docs.pdf"
      }
    },
    "1": {
      "type": "EMBED",
      "mutability": "IMMUTABLE",
      "data": {
        "url": "http://www.youtube.com/watch?v=y8Kyi0WNg40",
        "title": "Dramatic Look",
        "thumbnail": "/static/example-lowres-image2.jpg"
      }
    }
  }
}
```

--------------------------------

### Draft.js Content State JSON

Source: https://www.draftail.org/docs/introduction/decorators

Example of a raw Draft.js content state object containing text and code blocks.

```json
{
  "blocks": [
    {
      "key": "5d346",
      "text": "Sometimes #hashtags are useful.",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    },
    {
      "key": "23d6u",
      "text": "console.log('Hello, World!');",
      "type": "code-block",
      "depth": 0,
      "inlineStyleRanges": [],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Implement a Custom Image Entity Source

Source: https://www.draftail.org/docs/introduction/entities

Create a React component for an image entity source that uses window.prompt to get a URL, creates an immutable entity with the src, and inserts it as an atomic block. This component is given editorState and onComplete props.

```javascript
import { Component } from "react"
import { AtomicBlockUtils } from "draft-js"

class ImageSource extends Component {
  componentDidMount() {
    const { editorState, entityType, onComplete } = this.props

    const src = window.prompt("Image URL")

    if (src) {
      const content = editorState.getCurrentContent()
      const contentWithEntity = content.createEntity(
        entityType.type,
        "IMMUTABLE",
        { src },
      )
      const entityKey = contentWithEntity.getLastCreatedEntityKey()
      const nextState = AtomicBlockUtils.insertAtomicBlock(
        editorState,
        entityKey,
        " ",
      )

      onComplete(nextState)
    } else {
      onComplete(editorState)
    }
  }

  render() {
    return null
  }
}
```

--------------------------------

### Draftail Editor State for Disabled Toolbar

Source: https://www.draftail.org/docs/reference/customising-toolbars

Example of editor state representing a configuration where the toolbar is disabled.

```json
{
  "blocks": [
    {
      "key": "6bm5d",
      "text": "Disable the toolbar to save space if your editor only supports a handful of formats",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [
        {
          "offset": 23,
          "length": 10,
          "style": "ITALIC"
        }
      ],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Draftail content state JSON

Source: https://www.draftail.org/docs/introduction/inline-styles

Example of the raw JSON structure representing inline style ranges in Draftail content.

```json
{
  "blocks": [
    {
      "key": "c321i",
      "text": "This is redacted, and this is very bold.",
      "type": "unstyled",
      "depth": 0,
      "inlineStyleRanges": [
        {
          "offset": 8,
          "length": 8,
          "style": "REDACTED"
        },
        {
          "offset": 30,
          "length": 9,
          "style": "BOLD"
        }
      ],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Configure Custom Entity Allowlist and Attributes

Source: https://www.draftail.org/docs/introduction/entities

Define attributes to preserve and a regular expression for allowlisting specific entity sources, such as images starting with 'http'. This helps control data persistence during content pasting.

```javascript
{
    type: ENTITY_TYPE.IMAGE,
    icon: '#icon-image',
    // Preserve the src and alt attributes and no other.
    attributes: ['src', 'alt'],
    // Preserve images for which the src starts with "http".
    allowlist: {
        src: '^http',
    },
}
```

--------------------------------

### Log Hello World

Source: https://www.draftail.org/docs/introduction/decorators

A simple console log statement.

```javascript
console.log('Hello, World!');
```

--------------------------------

### Use data conversion helpers

Source: https://www.draftail.org/docs/controlled-component

Utilize createEditorStateFromRaw and serialiseEditorStateToRaw to handle content state initialization and serialization.

```javascript
import { createEditorStateFromRaw, serialiseEditorStateToRaw } from "draftail"  
  
// Initialise with `null` if there’s no preexisting state.  
const editorState = createEditorStateFromRaw(null)  
// Initialise with the raw content state otherwise.  
const editorState = createEditorStateFromRaw(rawContentState)  
  
// Content will be `null` if there’s no textual content, or RawDraftContentState otherwise.  
const content = serialiseEditorStateToRaw(editorState)  
```

--------------------------------

### Configure available formats

Source: https://www.draftail.org/docs/formatting-options

Define the available block types, inline styles, and entity types by populating these configuration arrays.

```javascript
// List of the available block types.  
blockTypes: [],  
// List of the available inline styles.  
inlineStyles: [],  
// List of the available entity types.  
entityTypes: [],  
```

--------------------------------

### Data Conversion Helpers

Source: https://www.draftail.org/docs/api

Utility functions to initialize editor state from raw content and serialize editor state back to raw content.

```APIDOC
## Data Conversion Helpers

### createEditorStateFromRaw
Creates a new EditorState from a RawDraftContentState. Passing `null` returns an empty editor state.

### serialiseEditorStateToRaw
Serializes the editorState using `convertToRaw`. Returns `null` if the editor content is empty.
```

--------------------------------

### Initialize Editor with Decorators

Source: https://www.draftail.org/docs/reference/api

Use the `decorators` prop to apply custom decorations to content within the editor. Each decorator requires a strategy function to identify decorated content and a React component to render the decoration.

```javascript
const editor = <DraftailEditor decorators={[...]} />  
```

--------------------------------

### Initialize Editor with Controls

Source: https://www.draftail.org/docs/reference/api

Use the `controls` prop to add custom controls to the editor's toolbar. Controls can be of type 'inline', 'block', or 'meta', and provide access to editor state manipulation functions.

```javascript
const editor = <DraftailEditor controls={[...]} />  
```

--------------------------------

### Initialize Editor with Inline Styles

Source: https://www.draftail.org/docs/reference/api

Use the `inlineStyles` prop to define custom inline styles for the editor. Each style requires a unique type and can optionally include CSS properties, a label, description, and icon.

```javascript
const editor = <DraftailEditor inlineStyles={[...]} />  
```

--------------------------------

### Draft.js ContentState Representation

Source: https://www.draftail.org/docs/reference/content-storage

This example shows the raw JSON structure of Draft.js ContentState, including blocks, inline styles, and entities. It is used for storing and serializing rich text content.

```javascript
const rawContentState = {
  blocks: [
    {
      // All blocks have a unique key, along with their text, and a type. "unstyled" is the default.
      key: "b1ito",
      text: "Example of the Draft.js ContentState.",
      type: "unstyled",
      // Blocks can have a depth greater than 0 when nested (e.g. list items).
      depth: 0,
      // Inline formatting is stored as ranges, which can overlap.
      inlineStyleRanges: [
        {
          offset: 15,
          length: 8,
          style: "BOLD",
        },
      ],
      // Entities (e.g. links) also use ranges, but do not overlap.
      // Entity ranges point to a key in the entity map.
      entityRanges: [
        {
          offset: 24,
          length: 12,
          key: 0,
        },
      ],
      // Additional data for the block.
      data: {},
    },
  ],
  entityMap: {
    0: {
      type: "LINK",
      mutability: "MUTABLE",
      data: {
        url: "https://draftjs.org/docs/api-reference-content-state/",
      },
    },
  },
}

```

--------------------------------

### Configure Plugins

Source: https://www.draftail.org/docs/api

Defines plugins for the editor using the plugins prop.

```javascript
const editor = <DraftailEditor plugins={[...]} />
```

--------------------------------

### Initialize Editor with Plugins

Source: https://www.draftail.org/docs/reference/api

Use the `plugins` prop to integrate external Draft.js plugins with the Draftail editor. The structure of each plugin follows the standard draft-js-plugins API.

```javascript
const editor = <DraftailEditor plugins={[...]} />  
```

--------------------------------

### Custom React Component for Icon Font

Source: https://www.draftail.org/docs/reference/customising-icons

Implement a custom React component to use an icon font for Draftail toolbar buttons. Ensure the component accepts an `icon` prop and applies the correct class names. This example shows how to integrate it with entity types.

```javascript
const FontIcon = ({ icon }) => (
  <span className={`icon icon-${icon}`} aria-hidden />
);

// And in the editor props:
entityTypes={[
  {
    type: "EMBED",
    description: "Embed",
    icon: <FontIcon icon="embed" />,
    source: EmbedSource,
    block: EmbedBlock,
    attributes: ["url", "title", "thumbnail"],
  }
]}
```

--------------------------------

### Initialize Editor with Block Types

Source: https://www.draftail.org/docs/reference/api

Use the `blockTypes` prop to define custom block types for the editor. Each block type requires a unique type and can optionally include a label, description, icon, and the DOM element for display.

```javascript
const editor = <DraftailEditor blockTypes={[...]} />  
```

--------------------------------

### Reusable UI Components

Source: https://www.draftail.org/docs/api

Reusable components for building consistent extensions, including Icon and ToolbarButton.

```APIDOC
## Reusable UI Components

### Icon
Used for consistent icon sizing.
- **icon** (string | string[] | JSX.Element) - Optional
- **title** (string | null) - Optional
- **className** (string | null) - Optional

### ToolbarButton
Used for building custom controls in the toolbar.
- **name** (string) - Optional
- **active** (boolean) - Required
- **label** (string) - Optional
- **title** (string) - Optional
- **icon** (IconProp) - Optional
- **onClick** (function) - Optional
```

--------------------------------

### Initialize DraftailEditor

Source: https://www.draftail.org/docs/api

Basic import and usage of the DraftailEditor component.

```typescript
import { DraftailEditor } from "draftail"  
  
const editor = <DraftailEditor />
```

--------------------------------

### Configure Sass variables with @use

Source: https://www.draftail.org/docs/reference/ui-theming

Override default editor styles by passing variables to the @use module system.

```scss
@use "draftail/src/index" with (  
  $draftail-editor-z-index: 100,  
  // Remove the editor's border and make the toolbar free-floating.  
  $draftail-editor-border: 0,  
  $draftail-editor-padding: 0,  
  $draftail-toolbar-radius: 5px  
);  

```

```scss
@use "draftail/src/index" as * with (  
  $draftail-editor-z-index: 100  
);  
  
.my-help-text {  
  color: $draftail-editor-text;  
}  

```

--------------------------------

### Importing HTML into Draftail

Source: https://www.draftail.org/docs/guides/importing-and-exporting-html

Configure draft-convert to map HTML elements to Draft.js entities and blocks, then initialize the editor with the resulting raw content state.

```javascript
import { convertToRaw, convertFromRaw } from "draft-js"  
import { convertFromHTML, convertToHTML } from "draft-convert"  
import { DraftailEditor, ENTITY_TYPE } from "draftail"  
  
const content = `  
<p>This editor demonstrates <strong>HTML import and export</strong>.</p>  
<hr />  
<blockquote>Built with <a href="https://github.com/HubSpot/draft-convert">draft-convert</a></blockquote>  
<img src="/static/example-lowres-image2.jpg"/>  
    <p></p>  
`  
  
const importerConfig = {  
  htmlToEntity: (nodeName, node, createEntity) => {  
    // a tags will become LINK entities, marked as mutable, with only the URL as data.  
    if (nodeName === "a") {  
      return createEntity(ENTITY_TYPE.LINK, "MUTABLE", { url: node.href })  
    }  
  
    if (nodeName === "img") {  
      return createEntity(ENTITY_TYPE.IMAGE, "IMMUTABLE", {  
        src: node.src,  
      })  
    }  
  
    if (nodeName === "hr") {  
      return createEntity(ENTITY_TYPE.HORIZONTAL_RULE, "IMMUTABLE", {})  
    }  
  
    return null  
  },  
  htmlToBlock: (nodeName) => {  
    if (nodeName === "hr" || nodeName === "img") {  
      // "atomic" blocks is how Draft.js structures block-level entities.  
      return "atomic"  
    }  
  
    return null  
  },  
}  
  
const fromHTML = (html) => convertToRaw(convertFromHTML(importerConfig)(html))  
  
const editor = (  
  <DraftailEditor  
    rawContentState={fromHTML(content)}  
    enableHorizontalRule  
    entityTypes={[  
      {  
        // We use the same value for type as in the converter.  
        type: ENTITY_TYPE.LINK,  
        source: LinkSource,  
        decorator: Link,  
        // We define what data the LINKs can have.  
        attributes: ["url"],  
        allowlist: {  
          href: "^(?![#/])",  
        },  
      },  
    ]}  
  />  
)
```

--------------------------------

### Configure built-in blocks

Source: https://www.draftail.org/docs/introduction/blocks

Use predefined block types from the BLOCK_TYPE constant to enable built-in functionality like blockquotes.

```javascript
import { BLOCK_TYPE } from 'draftail';  
  
blockTypes={[  
  {  
    type: BLOCK_TYPE.BLOCKQUOTE,  
  },  
]}  
```

--------------------------------

### Import Draft.js and Draftail Styles (Sass)

Source: https://www.draftail.org/docs/getting-started

Import the required CSS for Draft.js and Draftail in a Sass stylesheet.

```sass
@import "draft-js/dist/Draft";  
@import "draftail/dist/draftail";  

```

--------------------------------

### Import Editor Styles

Source: https://www.draftail.org/docs/introduction/getting-started

Include the necessary CSS for Draft.js and Draftail in your project.

```sass
@import "draft-js/dist/Draft";
@import "draftail/dist/draftail";
```

```javascript
import "draft-js/dist/Draft.css"
import "draftail/dist/draftail.css"
```

--------------------------------

### Initialize Draftail Editor

Source: https://www.draftail.org/docs/introduction/getting-started

Basic implementation of the DraftailEditor component with save functionality.

```javascript
import React from "react"
import ReactDOM from "react-dom"

import { DraftailEditor, BLOCK_TYPE, INLINE_STYLE } from "draftail"

const initial = JSON.parse(sessionStorage.getItem("draftail:content"))

const onSave = (content) => {
  console.log("saving", content)
  sessionStorage.setItem("draftail:content", JSON.stringify(content))
}

const editor = (
  <DraftailEditor
    rawContentState={initial || null}
    onSave={onSave}
    blockTypes={[
      { type: BLOCK_TYPE.HEADER_THREE },
      { type: BLOCK_TYPE.UNORDERED_LIST_ITEM },
    ]}
    inlineStyles={[{ type: INLINE_STYLE.BOLD }, { type: INLINE_STYLE.ITALIC }]}
  />
)

ReactDOM.render(editor, document.querySelector("[data-mount]"))
```

--------------------------------

### Reusable UI Components

Source: https://www.draftail.org/docs/reference/api

Draftail provides reusable UI components for building consistent extensions.

```APIDOC
## Reusable UI components

Some of Draftail’s UI components can be reused to more easily build extensions that are consistent.

### `Icon`

The Icon can be reused to have consistent icon sizing between different extensions and the toolbar.

```javascript
import { Icon } from "draftail"

const icon = <Icon icon="#square" />
```

Supported props:

```
icon?: string | string[] | JSX.Element;
title?: string | null;
className?: string | null;
```

There is further documentation about what formats are allowed for `icon`: Customising icons.

### `ToolbarButton`

The ToolbarButton can be reused when building custom `controls` in the toolbar.

```javascript
import { ToolbarButton } from "draftail"

const button = <ToolbarButton />
```

Supproted props:

```
name: ?string,
active: boolean,
label: ?string,
title: ?string,
icon: ?IconProp,
onClick: ?(string) => void,
```
```

--------------------------------

### Use legacy Sass import syntax

Source: https://www.draftail.org/docs/reference/ui-theming

Alternative method for importing styles or constants using the deprecated @import syntax.

```scss
// Increase the default editor z-index.  
$draftail-editor-z-index: 100;  
// Remove the editor's border and make the toolbar free-floating  
$draftail-editor-border: 0;  
$draftail-editor-padding: 0;  
$draftail-toolbar-radius: 5px;  
  
// Import all of the styles in your build.  
@import "draftail/src/index";  

```

```scss
@import "draftail/src/api/constants";  

```

--------------------------------

### Initialize Editor with Entity Types

Source: https://www.draftail.org/docs/reference/api

Use the `entityTypes` prop to define custom entity types for the editor. Each entity type requires a unique type and can include various configuration options for its source, decorator, block rendering, and paste handling.

```javascript
const editor = <DraftailEditor entityTypes={[...]} />  
```

--------------------------------

### Import Draft.js and Draftail Styles (Webpack/CRA)

Source: https://www.draftail.org/docs/getting-started

Import the required CSS for Draft.js and Draftail in a JavaScript file for Webpack or Create React App projects.

```javascript
import "draft-js/dist/Draft.css"  
import "draftail/dist/draftail.css"  

```

--------------------------------

### Configure Controls

Source: https://www.draftail.org/docs/api

Defines custom controls for the editor using the controls prop.

```javascript
const editor = <DraftailEditor controls={[...]} />
```

```javascript
// Or block or meta.  
inline: {  
  // Retrieve the full Draft.js EditorState.  
  getEditorState: () => EditorState,  
  // Change any part of the EditorState.  
  onChange: (EditorState) => void,  
}
```

--------------------------------

### Configure Entities

Source: https://www.draftail.org/docs/api

Defines entity types for the editor using the entityTypes prop.

```javascript
const editor = <DraftailEditor entityTypes={[...]} />
```

```javascript
// Unique type shared between entity instances.  
type: string,  
// Describes the control in the editor UI, concisely.  
label?: string | null;  
// Describes the control in the editor UI.  
description?: string | null;  
// Represents the control in the editor UI.  
icon?: IconProp;  
/** React component providing the UI to manage entities of this type. */  
source: React.ComponentType<EntitySourceProps>;  
  
/** React component to display inline entities. */  
decorator?: React.ComponentType<EntityDecoratorProps>;  
  
/** React component to display block-level entities. */  
block?: React.ComponentType<EntityBlockProps>;  
  
/** Custom copy-paste processing checker. */  
onPaste?: (  
  text: string,  
  html: string | null | undefined,  
  editorState: EditorState,  
  helpers: {  
    setEditorState: (state: EditorState) => void;  
    getEditorState: () => EditorState;  
  },  
  entityType: EntityTypeControl,  
) => "handled" | "not-handled";  
  
/** Array of attributes the entity uses, to preserve when filtering entities on paste.  
 * If undefined, all entity data is preserved.  
 */  
attributes?: ReadonlyArray<string>;  
  
/** Attribute - regex mapping, to preserve entities based on their data on paste.  
 * For example, { url: '^https:' } will only preserve links that point to HTTPS URLs.  
 */  
allowlist?: { [attr: string]: string };
```

--------------------------------

### Configure built-in inline styles

Source: https://www.draftail.org/docs/introduction/inline-styles

Use predefined types from the draftail library to enable built-in inline styles.

```javascript
import { INLINE_STYLE } from 'draftail';  
  
inlineStyles={[  
  {  
    type: INLINE_STYLE.BOLD,  
  },  
]}  
```

--------------------------------

### Formik Demo with Draftail

Source: https://www.draftail.org/docs/form-validation

A full demo integrating Draftail with Formik for validation. Enforces at least two paragraphs and one link. Uses `onSave` and `onBlur` to update Formik state.

```javascript
<Formik
  initialValues={{ content: null }}
  onSubmit={window.alert.bind(null, "Success!")}
  validate={(values) => {
    const errors = {}

    if (!values.content) {
      errors.content = "Please enter at least two paragraphs"
    } else {
      const { blocks, entityMap } = values.content
      if (Object.keys(entityMap).length === 0) {
        errors.content = "Please use at least one link"
      }

      // Check there are at least two blocks with non-whitespace text
      if (blocks.filter((b) => b.text.trim().length > 0).length < 2) {
        errors.content = "Please enter at least two paragraphs"
      }
    }

    return errors
  }}
>
  {(({ errors, touched, handleSubmit, setFieldTouched, setFieldValue }) => (
    <form onSubmit={handleSubmit}>
      <div className="form-field">
        <DraftailEditor
          entityTypes={[ENTITY_CONTROL.LINK]}
          onSave={setFieldValue.bind(null, "content")}
          onBlur={setFieldTouched.bind(null, "content")}
          stateSaveInterval={errors.content ? 50 : 250}
        />
        <div role="alert">
          {errors.content && touched.content && errors.content}
        </div>
      </div>
      <button type="submit">Submit</button>
    </form>
  ))}
</Formik>
```

--------------------------------

### Available Sass variables

Source: https://www.draftail.org/docs/reference/ui-theming

List of configurable Sass variables and their default values.

```scss
$draftail-base-spacing: 0.25rem !default;
$draftail-editor-padding: $button-spacing + $controls-spacing !default;
$draftail-editor-text: $color-grey !default;
$draftail-editor-background: $color-white !default;
$draftail-editor-readonly-opacity: 0.5 !default;
$draftail-editor-chrome: $color-light-grey !default;
$draftail-editor-chrome-text: $color-grey !default;
$draftail-editor-chrome-active: $color-black !default;
$draftail-editor-chrome-accent: color.adjust(
  $color: $draftail-editor-chrome,
  $lightness: -10%,
) !default;
$draftail-tooltip-chrome: $color-grey !default;
$draftail-tooltip-chrome-text: $color-white !default;
$draftail-editor-font-family: sans-serif !default;
$draftail-editor-font-size: 1rem !default;
$draftail-editor-line-height: 1.5 !default;
$draftail-placeholder-text: $color-grey-757575 !default;
$draftail-editor-border: 1px solid $draftail-editor-chrome !default;
$draftail-contrast-outline: var(
  --draftail-contrast-outline,
  2px solid transparent
) !default;
$draftail-contrast-outline-modal: var(
  --draftail-contrast-outline-modal,
  10px solid transparent
) !default;
$draftail-editor-radius: 5px !default;
$draftail-tooltip-radius: 5px !default;
$draftail-toolbar-radius: 0 !default;
$draftail-toolbar-tooltip-radius: 4px !default;
$draftail-toolbar-border-bottom: $draftail-editor-border !default;
$draftail-toolbar-tooltip-duration: 0.1s !default;
$draftail-toolbar-tooltip-delay: 1s !default;
$draftail-block-spacing: $draftail-base-spacing * 2 !default;
$draftail-editor-z-index: 1 !default;
$draftail-tooltip-z-index: $draftail-editor-z-index + 10 !default;
$draftail-overlay-z-index: $draftail-tooltip-z-index + 10 !default;
$draftail-toolbar-z-index: $draftail-overlay-z-index + 10 !default;
$draftail-toolbar-tooltip-z-index: $draftail-toolbar-z-index + 10 !default;
$draftail-page-overlay-z-index: $draftail-toolbar-z-index + 10 !default;

```

--------------------------------

### Implement a block-level entity

Source: https://www.draftail.org/docs/introduction/entities

Create a class component to render block-level entities, such as images, using data from blockProps.

```javascript
import React, { Component } from "react"  
  
class ImageBlock extends Component {  
  render() {  
    const { blockProps } = this.props  
    const { entity } = blockProps  
    const { src, alt } = entity.getData()  
  
    return <img className="ImageBlock" src={src} alt={alt} width="256" />  
  }  
}  
```

--------------------------------

### Configure Block Types

Source: https://www.draftail.org/docs/api

Defines block types for the editor using the blockTypes prop.

```javascript
const editor = <DraftailEditor blockTypes={[...]} />
```

```javascript
// Unique type shared between block instances.  
type: string,  
// Describes the control in the editor UI, concisely.  
label?: string | null;  
// Describes the control in the editor UI.  
description?: string | null;  
// Represents the control in the editor UI.  
icon?: IconProp;  
// DOM element used to display the block within the editor area.  
element?: string;
```

--------------------------------

### Decorator API

Source: https://www.draftail.org/docs/introduction/entities

Defines the props and implementation pattern for inline entity decorators.

```APIDOC
## Decorator Props

### Description
Decorators render inline entities based on their data and receive specific props for management.

### Parameters
- **entityKey** (string) - Required - The key of the decorated entity.
- **contentState** (ContentState) - Required - The editor’s content.
- **children** (React.ReactNode) - Required - Rich text to be displayed inside the decorator.
- **onEdit** (function) - Required - Shorthand to edit entity data.
- **onRemove** (function) - Required - Shorthand to remove an entity, and the related block.
- **textDirectionality** (TextDirectionality) - Optional - Optionally set the overriding text directionality for this editor.
```

--------------------------------

### Data Conversion Helpers

Source: https://www.draftail.org/docs/reference/api

Functions to help with converting between Draft.js RawDraftContentState and EditorState.

```APIDOC
## Data conversion helpers

Draftail exports the methods it uses internally to initialise the editor’s content via `rawContentState` and persist it in `onSave`: `createEditorStateFromRaw`, and `serialiseEditorStateToRaw`.

### `createEditorStateFromRaw`

Creates a new EditorState from a RawDraftContentState, or an empty editor state by passing `null`.

```javascript
createEditorStateFromRaw = (rawContentState: ?RawDraftContentState) => EditorState
```

### `serialiseEditorStateToRaw`

Serialises the editorState using `convertToRaw`, but returns `null` if the editor content is empty (no text, entities, styles).

```javascript
serialiseEditorStateToRaw = (editorState: EditorState) => RawDraftContentState
```
```

--------------------------------

### Block API

Source: https://www.draftail.org/docs/introduction/entities

Defines the props and implementation pattern for block-level entities.

```APIDOC
## Block Props

### Description
Blocks render block-level entities and provide controls for editing and manipulation.

### Parameters
- **block** (ContentBlock) - Required - The current content block.
- **blockProps** (object) - Required - Contains editor state, entity instances, and management methods like `onEditEntity`, `onRemoveEntity`, `lockEditor`, and `unlockEditor`.
```

--------------------------------

### Configure Draftail with Draft.js Plugins for Toolbars

Source: https://www.draftail.org/docs/reference/customising-toolbars

Use Draft.js plugins for advanced toolbars by setting them as the bottom toolbar. Plugin components cannot be placed above the editor.

```jsx
<DraftailEditor  
  plugins={[inlineToolbarPlugin, sideToolbarPlugin]}  
  topToolbar={null}  
  bottomToolbar={(props) => (  
    <>
      <SideToolbar {...props} />  
      <InlineToolbar {...props} />  
    </>
  )}  
/>  

```

--------------------------------

### Basic Draftail Editor Implementation

Source: https://www.draftail.org/docs/getting-started

A simple React component demonstrating the Draftail editor with H3, bullet list, bold, and italic formatting options. It saves content to sessionStorage.

```javascript
import React from "react"  
import ReactDOM from "react-dom"  
  
import { DraftailEditor, BLOCK_TYPE, INLINE_STYLE } from "draftail"  
  
const initial = JSON.parse(sessionStorage.getItem("draftail:content"))  
  
const onSave = (content) => {  
  console.log("saving", content)  
  sessionStorage.setItem("draftail:content", JSON.stringify(content))  
}  
  
const editor = (  
  <DraftailEditor  
    rawContentState={initial || null}  
    onSave={onSave}  
    blockTypes={[  
      { type: BLOCK_TYPE.HEADER_THREE },  
      { type: BLOCK_TYPE.UNORDERED_LIST_ITEM },  
    ]}  
    inlineStyles={[{ type: INLINE_STYLE.BOLD }, { type: INLINE_STYLE.ITALIC }]}  
  />  
)  
  
ReactDOM.render(editor, document.querySelector("[data-mount]"))  

```

--------------------------------

### Create EditorState from Raw Content

Source: https://www.draftail.org/docs/reference/api

Initializes an EditorState from a RawDraftContentState. Pass null to create an empty editor state.

```typescript
createEditorStateFromRaw = (rawContentState: ?RawDraftContentState) =>  
  EditorState  
```

--------------------------------

### Configure Decorators

Source: https://www.draftail.org/docs/api

Defines decorators for the editor using the decorators prop.

```javascript
const editor = <DraftailEditor decorators={[...]} />
```

```javascript
// Determines which pieces of content are to be decorated.  
strategy: (block: ContentBlock, callback: (start: number, end: number) => void, contentState: ContentState) => void,  
// React component to display the decoration.  
component: ComponentType<{}>,
```

--------------------------------

### Draft.js ContentState Structure

Source: https://www.draftail.org/blog/2018/03/05/why-wagtail-new-editor-is-built-with-draft-js

Illustrates the JSON structure of Draft.js ContentState, showing blocks with text, type, and ranges for inline styles like 'BOLD'. Use this as a reference for understanding Draft.js data representation.

```json
{
  "blocks": [
    {
      "key": "b1ito",
      "text": "Rethinking rich text pipelines with Draft.js",
      "type": "header-one",
      "depth": 0,
      "inlineStyleRanges": [
        {
          "offset": 10,
          "length": 4,
          "style": "BOLD"
        }
      ],
      "entityRanges": [],
      "data": {}
    }
  ],
  "entityMap": {}
}
```

--------------------------------

### Configure Inline Styles

Source: https://www.draftail.org/docs/api

Defines inline styles for the editor using the inlineStyles prop.

```javascript
const editor = <DraftailEditor inlineStyles={[...]} />
```

```javascript
// Unique type shared between inline style instances.  
type: string,  
// CSS properties (in JS format) to apply for styling within the editor area.  
style?: CSSProperties;  
// Describes the control in the editor UI, concisely.  
label?: string | null;  
// Describes the control in the editor UI.  
description?: string | null;  
// Represents the control in the editor UI.  
icon?: IconProp;
```

--------------------------------

### Define CSS for media elements

Source: https://www.draftail.org/examples

CSS snippet for styling media containers and images within the editor.

```css
.media .img {
    margin-inline-end: 10px;
}
```

--------------------------------

### Configure Draftail HTML Exporter

Source: https://www.draftail.org/docs/guides/importing-and-exporting-html

Configure the exporter to handle blockquotes, atomic blocks, links, images, and horizontal rules. Use the same identifiers as Draftail for consistent conversion.

```javascript
import { convertToRaw, convertFromRaw } from "draft-js"  
import { convertFromHTML, convertToHTML } from "draft-convert"  
import { DraftailEditor, ENTITY_TYPE } from "draftail"  
  
const exporterConfig = {  
  blockToHTML: (block) => {  
    if (block.type === BLOCK_TYPE.BLOCKQUOTE) {  
      return <blockquote />  
    }  

    // Discard atomic blocks, as they get converted based on their entity.  
    if (block.type === BLOCK_TYPE.ATOMIC) {  
      return {  
        start: "",  
        end: "",  
      }  
    }  

    return null  
  },  
  
  entityToHTML: (entity, originalText) => {  
    if (entity.type === ENTITY_TYPE.LINK) {  
      return <a href={entity.data.url}>{originalText}</a>  
    }  

    if (entity.type === ENTITY_TYPE.IMAGE) {  
      return <img src={entity.data.src} alt={entity.data.alt} />  
    }  

    if (entity.type === ENTITY_TYPE.HORIZONTAL_RULE) {  
      return <hr />  
    }  

    return originalText  
  },  
}

const toHTML = (raw) =>  
  raw ? convertToHTML(exporterConfig)(convertFromRaw(raw)) : ""  
  
const editor = (  
  <DraftailEditor  
    onSave={(raw) => {  
      console.log(toHTML(raw))  
    }}  
    enableHorizontalRule  
    entityTypes={[  
      {  
        // We use the same value for type as in the converter.  
        type: ENTITY_TYPE.LINK,  
        source: LinkSource,  
        decorator: Link,  
        // We define what data the LINKs can have.  
        attributes: ["url"],  
        allowlist: {  
          href: "^(?![#/])",  
        },  
      },  
    ]}  
  />  
)
```

--------------------------------

### Create EditorState from Raw Content

Source: https://www.draftail.org/docs/api

Initializes a Draftail editor state from a RawDraftContentState object. Pass null to create an empty editor state.

```javascript
createEditorStateFromRaw = (rawContentState: ?RawDraftContentState) =>  
  EditorState  

```

--------------------------------

### Style custom blocks with CSS

Source: https://www.draftail.org/docs/introduction/blocks

Apply custom styles to blocks using the generated CSS class name following the pattern Draftail-block--[type].

```css
.Draftail-block--tiny-text {  
  font-size: 0.7625rem;  
  font-style: italic;  
}  
```

--------------------------------

### Draftail 'controls' Prop Configuration

Source: https://www.draftail.org/docs/introduction/arbitrary-controls

Defines the structure and usage of the 'controls' prop for adding custom toolbar components in Draftail.

```APIDOC
## Prop: controls

### Description
Allows adding arbitrary controls to the Draftail toolbar. Each control is an object that maps to a React component provided with editor state management functions.

### Parameters
#### Request Body
- **controls** (Array<Object>) - Required - An array of control objects.
  - **inline** (React Component) - Optional - Component for the floating toolbar.
  - **block** (React Component) - Optional - Component for the top static toolbar.
  - **meta** (React Component) - Optional - Component for the bottom meta toolbar.
  - **type** (String) - Optional - Identifier for troubleshooting.

### Component Props
- **getEditorState** (Function) - Returns the current Draft.js EditorState.
- **onChange** (Function) - Updates the editor state with a new EditorState.

### Usage Example
<DraftailEditor controls={[{ inline: MyCustomComponent, type: 'custom-control' }]} />
```

--------------------------------

### Benchmark null value

Source: https://www.draftail.org/docs/formatting-options

A benchmark output showing a null value.

```text
null
```
Tokens:
Raw