https://github.com/amr258144/draft-js-html-converter

A lightweight, zero-dependency library for converting between Draft.js rich text format and HTML
https://github.com/amr258144/draft-js-html-converter

bidirectional draft-js draftjs-to-html editor html javascript npm-package rich-text typescript zero-dependencies

Last synced: 16 days ago
JSON representation

A lightweight, zero-dependency library for converting between Draft.js rich text format and HTML

Host: GitHub
URL: https://github.com/amr258144/draft-js-html-converter
Owner: amr258144
License: mit
Created: 2025-08-15T06:17:06.000Z (about 2 months ago)
Default Branch: main
Last Pushed: 2025-08-15T16:47:11.000Z (about 2 months ago)
Last Synced: 2025-09-18T02:38:31.119Z (20 days ago)
Topics: bidirectional, draft-js, draftjs-to-html, editor, html, javascript, npm-package, rich-text, typescript, zero-dependencies
Language: JavaScript
Homepage: https://www.npmjs.com/package/draft-js-html-converter
Size: 53.7 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

          # Draft.js HTML Converter

[![npm version](https://badge.fury.io/js/draft-js-html-converter.svg)](https://www.npmjs.com/package/draft-js-html-converter)

[![GitHub license](https://img.shields.io/github/license/amr258144/draft-js-html-converter.svg)](https://github.com/amr258144/draft-js-html-converter/blob/main/LICENSE)

[![GitHub issues](https://img.shields.io/github/issues/amr258144/draft-js-html-converter.svg)](https://github.com/amr258144/draft-js-html-converter/issues)

[![GitHub stars](https://img.shields.io/github/stars/amr258144/draft-js-html-converter.svg)](https://github.com/amr258144/draft-js-html-converter/stargazers)

A lightweight, zero-dependency library for converting between Draft.js rich text format and HTML.

## Table of Contents

- [Why Choose This Library?](#why-choose-this-library)

- [Installation](#installation)

- [Quick Start](#quick-start)

- [Features](#features)

- [Usage](#usage)

- [API Reference](#api-reference)

- [Supported Features](#supported-features)

- [Examples](#examples)

- [Error Handling](#error-handling)

- [Browser Support](#browser-support)

- [Testing](#testing)

- [Troubleshooting](#troubleshooting)

- [Contributing](#contributing)

- [Related Projects](#related-projects)

- [Changelog](#changelog)

- [License](#license)

## Why Choose This Library?

- 🚀 **Zero dependencies** - No bloat, just pure JavaScript

- 📦 **Lightweight** - Less than 15KB minified

- ⚡ **Fast** - Optimized for performance

- 🔄 **Bidirectional** - Perfect round-trip conversion

- 🧪 **Well tested** - 95%+ test coverage

- 📘 **TypeScript ready** - Full type definitions included

## Installation

```bash

# npm

npm install draft-js-html-converter

# yarn

yarn add draft-js-html-converter

# pnpm

pnpm add draft-js-html-converter

```

## Quick Start

```javascript

const { convertRichTextToHtml, convertHtmlToDraftJs } = require('draft-js-html-converter');

// Draft.js to HTML

const html = convertRichTextToHtml(draftContent);

// HTML to Draft.js  

const draftContent = convertHtmlToDraftJs('
Hello World');

```

## Features

- ✅ Convert Draft.js content to clean HTML

- ✅ Convert HTML back to Draft.js format

- ✅ Support for all common formatting (bold, italic, underline, headers, lists, links, colors, font sizes)

- ✅ Proper handling of nested styles and entities

- ✅ Text alignment support

- ✅ Zero dependencies

- ✅ TypeScript support

- ✅ Comprehensive test coverage

- ✅ Round-trip conversion support

## Usage

### Converting Draft.js to HTML

```javascript

const { convertRichTextToHtml } = require('draft-js-html-converter');

const draftContent = {

  blocks: [

    {

      key: 'abc123',

      data: {},

      text: 'Hello World',

      type: 'unstyled',

      depth: 0,

      entityRanges: [],

      inlineStyleRanges: [

        { style: 'BOLD', offset: 0, length: 5 }

      ]

    }

  ],

  entityMap: {}

};

const html = convertRichTextToHtml(draftContent);

console.log(html); // '
Hello World'

```

### Converting HTML to Draft.js

```javascript

const { convertHtmlToDraftJs } = require('draft-js-html-converter');

const html = '
Hello World';

const draftContent = convertHtmlToDraftJs(html);

console.log(draftContent);

// {

//   blocks: [

//     {

//       key: 'generated-key',

//       data: {},

//       text: 'Hello World',

//       type: 'unstyled',

//       depth: 0,

//       entityRanges: [],

//       inlineStyleRanges: [

//         { style: 'BOLD', offset: 0, length: 5 }

//       ]

//     }

//   ],

//   entityMap: {}

// }

```

### ES6 Imports

```javascript

import { convertRichTextToHtml, convertHtmlToDraftJs } from 'draft-js-html-converter';

// or

import converter from 'draft-js-html-converter';

const html = converter.convertRichTextToHtml(draftContent);

```

## API Reference

### convertRichTextToHtml(richTextContent)

Converts Draft.js content to HTML string.

**Parameters:**

- `richTextContent` (Object): Draft.js content state object

**Returns:**

- `string`: HTML representation of the content

### convertHtmlToDraftJs(htmlContent)

Converts HTML string to Draft.js content format.

**Parameters:**

- `htmlContent` (string): HTML content to convert

**Returns:**

- `Object`: Draft.js content state object with `blocks` and `entityMap`

## Supported Features

### Block Types

- `unstyled` → `
`

- `header-one` → `
`

- `header-two` → `
`

- `header-three` → `
`

- `unordered-list-item` → ``

- `ordered-list-item` → ``

- `blockquote` → ``

- `code-block` → ``

### Inline Styles

- `BOLD` → ``

- `ITALIC` → ``

- `UNDERLINE` → ``

- `FONT_SIZE_SMALL` → ``

- `FONT_SIZE_NORMAL` → ``

- `FONT_SIZE_LARGE` → ``

- `FONT_SIZE_HUGE` → ``


### Entities

- Links: `{ type: 'CUSTOM', data: { url: '...' } }` → ``

- Colors: `{ type: 'CUSTOM', data: { color: '...' } }` → ``


### Block Data

- Text alignment: `{ textAlignment: 'center' }` → `style="text-align: center"`

## Examples

🔗 **[Try it online](https://codesandbox.io/s/draft-js-html-converter-demo)** (CodeSandbox)

### Complex Content with Multiple Styles

```javascript

const complexDraft = {

  blocks: [

    {

      key: 'header',

      data: { textAlignment: 'center' },

      text: 'Welcome to My Blog',

      type: 'header-one',

      depth: 0,

      entityRanges: [],

      inlineStyleRanges: []

    },

    {

      key: 'intro',

      data: {},

      text: 'This is an introduction with bold text and a link to Google.',

      type: 'unstyled',

      depth: 0,

      entityRanges: [{ key: 0, offset: 53, length: 6 }],

      inlineStyleRanges: [{ style: 'BOLD', offset: 29, length: 4 }]

    },

    {

      key: 'list1',

      data: {},

      text: 'First item',

      type: 'unordered-list-item',

      depth: 0,

      entityRanges: [],

      inlineStyleRanges: []

    },

    {

      key: 'list2',

      data: {},

      text: 'Second item with italic text',

      type: 'unordered-list-item',

      depth: 0,

      entityRanges: [],

      inlineStyleRanges: [{ style: 'ITALIC', offset: 17, length: 6 }]

    }

  ],

  entityMap: {

    0: {

      type: 'CUSTOM',

      mutability: 'MUTABLE',

      data: { url: 'https://google.com' }

    }

  }

};

const html = convertRichTextToHtml(complexDraft);

console.log(html);

// Output:

// 
Welcome to My Blog

// This is an introduction with bold text and a link to Google.

// 

//   First item

//   Second item with italic text

// 

```

### Round-trip Conversion

```javascript

// Start with HTML

const originalHtml = `

  
My Article

  This is a paragraph with bold and italic text.

  

    List item 1

    List item 2

  

`;

// Convert to Draft.js

const draftContent = convertHtmlToDraftJs(originalHtml);

// Convert back to HTML

const finalHtml = convertRichTextToHtml(draftContent);

// The content is preserved through the round-trip

console.log(finalHtml);

```

## Error Handling

The library includes robust error handling:

- Invalid or malformed input returns safe fallback values

- HTML parsing errors are caught and logged

- Malformed Draft.js content falls back to JSON string representation

```javascript

// These all handle gracefully

convertRichTextToHtml(null); // returns ''

convertRichTextToHtml({}); // returns ''

convertHtmlToDraftJs(''); // returns { blocks: [], entityMap: {} }

convertHtmlToDraftJs('html'); // returns safe fallback structure

```

## Browser Support

- Chrome 60+

- Firefox 55+

- Safari 12+

- Edge 79+

- Node.js 12+

## Testing

Run the test suite:

```bash

npm test

```

The library includes comprehensive tests covering:

- All supported block types and inline styles

- Entity handling (links, colors)

- Edge cases and error conditions

- Round-trip conversion accuracy

- Malformed input handling

## Troubleshooting

### Common Issues

**Q: My inline styles aren't converting correctly**

A: Check that your `offset` and `length` values in `inlineStyleRanges` match the actual text positions.

**Q: Links aren't working**

A: Ensure your entity has `type: 'CUSTOM'` and `data: { url: '...' }`.

**Q: Getting empty output**

A: Verify your Draft.js content has the correct structure with `blocks` and `entityMap`.

### Need Help?

- 📖 [Check the examples](./examples/)

- 🐛 [Report a bug](https://github.com/amr258144/draft-js-html-converter/issues)

- 💬 [Ask a question](https://github.com/amr258144/draft-js-html-converter/discussions)

## Contributing

1. Fork the repository

2. Create your feature branch (`git checkout -b feature/amazing-feature`)

3. Add tests for your changes

4. Ensure all tests pass (`npm test`)

5. Commit your changes (`git commit -m 'Add amazing feature'`)

6. Push to the branch (`git push origin feature/amazing-feature`)

7. Open a Pull Request

## Related Projects

- [Draft.js](https://draftjs.org/) - Rich text editor framework

- [draft-js-export-html](https://github.com/sstur/draft-js-export-html) - Alternative HTML export (Draft.js → HTML only)

- [draft-js-import-html](https://github.com/sstur/draft-js-import-html) - Alternative HTML import (HTML → Draft.js only)

**Why choose draft-js-html-converter?** Bidirectional conversion, zero dependencies, and comprehensive feature support in one package.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for a detailed list of changes.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/amr258144/draft-js-html-converter

Awesome Lists containing this project

README

`
- `header-two` → `

`
- `header-three` → `

Welcome to My Blog

My Article

https://github.com/amr258144/draft-js-html-converter

Awesome Lists containing this project

README

` - `header-two` → `

` - `header-three` → `

Welcome to My Blog

My Article

`
- `header-two` → `

`
- `header-three` → `