diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index c2300f63..7c451ff7 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,13 +1,43 @@ -Thanks for filing an issue! +Thanks for filing an issue! -If at all possible, please provide a Codepen to demonstrate the problem you're having with React Quill. Here's a [template] to get you started. +If at all possible, please provide a Codesandbox or Codepen to demonstrate the problem you're having with React Quill. Here's a [template] to get you started. + +⚠️ Make sure that your bug hasn't already been fixed by ReactQuill `v2.0.0-beta.2`. See the homepage for instructions on how to upgrade. + +[template]: +https://codesandbox.io/s/react-quill-template-u9c9c + + +### Ticket due diligence + +- [ ] I have verified that the issue persists under ReactQuill `v2.0.0-beta.2` +- [ ] I can't use the beta version for other reasons + + +### ReactQuill version + +- [ ] master +- [ ] v2.0.0-beta.2 +- [ ] v2.0.0-beta.1 +- [ ] 1.3.5 +- [ ] 1.3.4 or older +- [ ] Other (fork) -[template]: -https://codepen.io/pen?template=xgyOXQ ### FAQ +**Is this a bug in Quill or ReactQuill?** + +ReactQuill is just a ~thin~ wrapper on top of the Quill editor. Often, what looks like a bug in ReactQuill, is actually a bug in the Quill editor itself. Before opening a ticket, please check the [Quill documentation], and the [issues page], and see if that answers your question first. + +[Quill documentation]: +https://quilljs.com/docs + +[issues page]: +https://github.com/quilljs/quill/issues + **How do I access the wrapped Quill instance?** + See the [instance methods] and [API] documentation. [instance methods]: @@ -15,24 +45,3 @@ https://github.com/zenoamaro/react-quill#methods [API]: https://github.com/zenoamaro/react-quill#api-reference - -**Is there a bug in Quill?** -Please refer to the [Quill issues page]. - -[Quill issues page]: -https://github.com/quilljs/quill/issues - -#### React-Quill version -- [ ] master -- [ ] 0.4.1 -- [ ] 1.0.0-beta-1 -- [ ] 1.0.0-beta-2 -- [ ] 1.0.0-beta-3 -- [ ] 1.0.0-beta-4 -- [ ] 1.0.0-beta-5 -- [ ] 1.0.0-rc-1 -- [ ] 1.0.0-rc-2 -- [ ] 1.0.0-rc-3 -- [ ] 1.0.0 -- [ ] 1.1.0 -- [ ] Other (fork) diff --git a/.gitignore b/.gitignore index 50daf201..978bb651 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,7 @@ # Packaging artifacts /react-quill-*.tgz /package + +# Test artifacts +.cypress/screenshots +.cypress/videos diff --git a/.jshintrc b/.jshintrc deleted file mode 100644 index 768ed52a..00000000 --- a/.jshintrc +++ /dev/null @@ -1,27 +0,0 @@ -{ - "browser": true, - "node": true, - "bitwise": true, - "camelcase": true, - "curly": false, - "eqeqeq": true, - "expr": true, - "freeze": true, - "latedef": false, - "noarg": true, - "newcap": false, - "noempty": true, - "nonbsp": true, - "nonew": true, - "quotmark": "single", - "undef": true, - "unused": false, - "strict": true, - "maxdepth": 3, - "maxparams": 4, - "maxcomplexity": 8, - "maxlen": 100, - "eqnull": true, - "lastsemic": true, - "laxbreak": true -} \ No newline at end of file diff --git a/.npmignore b/.npmignore deleted file mode 100644 index d073b18f..00000000 --- a/.npmignore +++ /dev/null @@ -1,11 +0,0 @@ -*~ -~* -*.tmp -*.orig -*.bak -*.log -/tmp -/node_modules -/src -/test -/package \ No newline at end of file diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 00000000..c1a6f667 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,4 @@ +{ + "singleQuote": true, + "trailingComma": "es5" +} diff --git a/.travis.yml b/.travis.yml index 5d80de36..0947ad80 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,12 +1,19 @@ language: node_js - node_js: - - "node" - + - 10 +addons: + apt: + packages: + # Ubuntu 16+ does not install this dependency by default, so we need to install it ourselves + - libgconf-2-4 +cache: + # Caches $HOME/.npm when npm ci is default script command + # Caches node_modules in all other cases + npm: true + directories: + # we also need to cache folder with Cypress binary + - ~/.cache install: - npm install - script: - - make build - - make spec - - make lint + - npm run test diff --git a/CHANGELOG.md b/CHANGELOG.md index ffe80aa0..68d29ca0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,61 +1,62 @@ -Changelog -========= +# Changelog -v1.3.3 ------- +## v2.0.0 + +- Fully ported to TypeScript (#549) +- Fully React16 compliant (#549) +- Removed Mixin (#549) +- Removed Toolbar (#549) +- Support for React 18 (#793, #822) + +## v1.3.4 + +- Bump Quill to 1.3.7 to close a security vulnerability (#575) + +## v1.3.3 - Pin Quill types version (#420 @daggmano) -v1.3.2 ------- +## v1.3.2 -- Add preserveWhitespace prop (#407 @royshouvik) +- Add preserveWhitespace prop (#407 @royshouvik) -v1.3.1 ------- +## v1.3.1 - Add back default export (#374, #384 one19) -v1.3.0 ------- +## v1.3.0 - Add scrollingContainer prop -- Fix Typescript exports +- Fix Typescript exports - Fix tabindex prop -v1.2.6 ------- +## v1.2.6 Replaced React.DOM with react-dom-factories (#319 thienanle) -v1.2.5 ------- +## v1.2.5 - Fix issue with unnecessary editor focus on mount (#321 jetzhou) - Switch to Quill's clipboard.convert from the paste API that now grabs focus automatically -v1.2.4 ------- +## v1.2.4 - Only restore focus if editor had focus (#312 @MattKunze) - -v1.2.2 ------- +## v1.2.2 - Add Typescript definitions (#277 @Charrondev) -- Fixes for TS definitions (#294 @jdhungtington, #296 @ajaska) +- Fixes for TS definitions (#294 @jdhungtington, #296 @ajaska) -v1.1.0 ------- +## v1.1.0 - Add support for React 16 and onwards by depending on `prop-types` and `create-react-class` (#181 @mikecousins) - Allow setting contents with a Quill Delta via the `value` prop (#101) - Add onFocus/onBlur props (#110) - Add tabindex support (#232) -v1.0.0 ------- +## v1.0.0 + This release supports Quill v1.0.0+. ⚠️ There are many breaking changes, so refer to the documentation for information on how to migrate your application. - Updated to support Quill v1.0.0+ (@clemmy, @alexkrolick) @@ -97,12 +98,12 @@ This release supports Quill v1.0.0+. ⚠️ There are many breaking changes, so - Updated React peerDependency (@rpellerin) - Removed inline Parchment formats for font-size and font-family (#217) -v0.4.1 ------- +## v0.4.1 + - Added contents of `dist` to NPM package. -v0.4.0 ------- +## v0.4.0 + This release finally adds support for React 0.14. ⚠️ Shims to support older versions of React have been removed. - React 0.14 support (@jacktrades, #49) @@ -116,8 +117,8 @@ This release finally adds support for React 0.14. ⚠️ Shims to support older - Quill stylesheets are now linked to `dist/` for convenience. (#70) - Exposed editor accessor methods in change events. (#33) -v0.3.0 ------- +## v0.3.0 + - Bumped Quill.js to v0.2.0 - Exposed `focus` and `blur` public methods from component. - Exposed `getEditor` public method to retrieve the backing Quill instance from the component. @@ -133,60 +134,60 @@ v0.3.0 - Fixes an issue where the editor would be instantiated with the wrong value. Fixes #50. - Avoiding parsing Quill's `dist` directory with webpack. -v0.2.2 ------- +## v0.2.2 + - Added missing `modules` propType and documentation. - Children are now cloned so ReactQuill can own their refs. Fixes #20. -v0.2.1 ------- +## v0.2.1 + - Link toolbar button and module are now enabled by default. Fixes #19. -v0.2.0 ------- +## v0.2.0 + - Fix React warnings about unique `key` props in toolbar (@Janekk). - Sending `delta` and `source` from editor change events. Fixes #17. - Rewritten uncontrolled and semi-controlled operation. Should fix #9, #10 and #14. - Editor props can now be changed after mounting. - Added callback for selection change event. Closes #12. -v0.1.1 ------- +## v0.1.1 + - The pre-compiled distributable is not shipped with the NPM package anymore. Should fix #2. - Sourcemaps are now emitted for both distributables, as separate files. - Avoiding parsing Quill as it ships with a pre-built main. -v0.1.0 ------- +## v0.1.0 + - Added support for toolbar separators. - Added support for font family selectors. - Updated the default toolbar to match Quill's. - Updated Quill to v0.19.12. -v0.0.6 ------- +## v0.0.6 + - Added keywords for inclusion in [React.parts](https://react.parts). -v0.0.5 ------- +## v0.0.5 + - Default empty content for components with no value. - Fixes wrong `QuillToolbar` propType. -v0.0.4 ------- +## v0.0.4 + - Added color toggle to toolbar (@chrismcv) - Exporting default item sets on `QuillToolbar` - Fixed `QuillComponent` only accepting a single child. -v0.0.3 ------- +## v0.0.3 + - Switched from `quilljs` package to `quill`. - Using the new `destroy()` from Quill. -v0.0.2 ------- +## v0.0.2 + - Compatible with React 0.12. -v0.0.1 ------- +## v0.0.1 + - Initial version. diff --git a/LICENSE b/LICENSE index 460c9c8a..06ce3d58 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016, zenoamaro +Copyright (c) 2020, zenoamaro Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Makefile b/Makefile deleted file mode 100644 index 16af2810..00000000 --- a/Makefile +++ /dev/null @@ -1,47 +0,0 @@ -LINT=./node_modules/.bin/jshint -LINT_FLAGS= -TEST=./node_modules/.bin/mocha --recursive --require=./test/setup.js -SPEC_FLAGS=-R spec -COVERAGE_FLAGS=-R mocha-text-cov -WEBPACK=./node_modules/.bin/webpack -SOURCE=./src -LIB=./lib - -usage: - @echo lint: lints the source - @echo spec: runs the test specs - @echo coverage: runs the code coverage test - @echo test: lint, spec and coverage threshold test - @echo build: builds the minified version - @echo clean: removes the build artifacts - -lint: - @$(LINT) $(LINT_FLAGS) $(SOURCE) - -spec: - @$(TEST) $(SPEC_FLAGS) test/index - -coverage: - @$(TEST) $(COVERAGE_FLAGS) test/index - -test: - @make lint - @make spec - @make coverage COVERAGE_FLAGS="-R travis-cov" - -build: - @$(WEBPACK) --config webpack.dev.js - @$(WEBPACK) --config webpack.prod.js - @cp node_modules/quill/dist/quill.core.css dist - @cp node_modules/quill/dist/quill.snow.css dist - @cp node_modules/quill/dist/quill.bubble.css dist - @mkdir -p $(LIB) - @cp -Rfv $(SOURCE)/* $(LIB) - -watch: - @$(WEBPACK) --watch --config webpack.dev.js - -clean: - @if [ -d dist ]; then rm -r dist; fi - @if [ -d lib ]; then rm -r lib; fi -.PHONY: usage test spec coverage lint build clean diff --git a/README.md b/README.md index edb6cc2b..8f2b576a 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,118 @@ -React-Quill [![Build Status](https://travis-ci.org/zenoamaro/react-quill.svg?branch=master)](https://travis-ci.org/zenoamaro/react-quill) [![npm](https://img.shields.io/npm/v/react-quill.svg)](https://www.npmjs.com/package/react-quill) +ReactQuill [![Build Status](https://travis-ci.org/zenoamaro/react-quill.svg?branch=master)](https://travis-ci.org/zenoamaro/react-quill) [![npm](https://img.shields.io/npm/v/react-quill.svg)](https://www.npmjs.com/package/react-quill) [![npm downloads](https://img.shields.io/npm/dt/react-quill.svg?maxAge=2592000)](http://www.npmtrends.com/react-quill) ============================================================================== A [Quill] component for [React]. +> **2025 Note** +> +> You probably don't need this library to use Quill with React. See https://quilljs.com/playground/react + See a [live demo] or [Codepen](http://codepen.io/alexkrolick/pen/xgyOXQ/left?editors=0010#0). -[Quill]: https://quilljs.com -[React]: https://facebook.github.io/react/ +[quill]: https://quilljs.com +[react]: https://facebook.github.io/react/ [live demo]: https://zenoamaro.github.io/react-quill/ -1. [Quick start](#quick-start) - 1. [Import the component](#import-the-component) - 1. [Import the stylesheet](#import-the-stylesheet) - 1. [Use the component](#use-the-component) - 1. [Using Deltas](#using-deltas) - 1. [Controlled vs Uncontrolled Mode](#controlled-vs-uncontrolled-mode) -1. [Options](#options) - 1. [Theme](#theme) - 1. [Custom Toolbar](#custom-toolbar) - 1. [Custom Formats](#custom-formats) - 1. [Custom Editing Area](#custom-editing-area) - 1. [Mixin](#mixin) -1. [Upgrading to React-Quill v1.0.0](#upgrading-to-react-quill-v100) -1. [API reference](#api-reference) - 1. [Exports](#exports) - 1. [Props](#props) - 1. [Methods](#methods) -1. [Browser support](#browser-support) -1. [Building and testing](#building-and-testing) - 1. [Bundling with Webpack](#bundling-with-webpack) -1. [Changelog](./CHANGELOG.md) -1. [Contributors](#contributors) -1. [License](#license) +- [Quick Start](#quick-start) + - [With webpack or create-react-app](#with-webpack-or-create-react-app) + - [With the browser bundle](#with-the-browser-bundle) +- [Usage](#usage) + - [Controlled mode caveats](#controlled-mode-caveats) + - [Using Deltas](#using-deltas) + - [Themes](#themes) + - [Custom Toolbar](#custom-toolbar) + - [Default Toolbar Elements](#default-toolbar-elements) + - [HTML Toolbar](#html-toolbar) + - [Custom Formats](#custom-formats) + - [Custom editing area](#custom-editing-area) +- [Upgrading to ReactQuill v2](#upgrading-to-reactquill-v2) + - [Deprecated props](#deprecated-props) + - [ReactQuill Mixin](#reactquill-mixin) + - [Toolbar component](#toolbar-component) +- [API reference](#api-reference) + - [Exports](#exports) + - [Props](#props) + - [Methods](#methods) + - [The unprivileged editor](#the-unprivileged-editor) +- [Building and testing](#building-and-testing) +- [Browser support](#browser-support) +- [Changelog](#changelog) +- [Contributors](#contributors) +- [License](#license) --- -💯 **React Quill now supports Quill v1.0.0!** -Thanks to @clemmy and @alexkrolick for landing this much-awaited change. There are many breaking changes, so be sure to read the [migration guide](#upgrading-to-react-quill-v100). +This is the documentation for ReactQuill v2 — Previous releases: [v1](/../../tree/v1) --- -```sh -npm install react-quill -yarn add react-quill -``` +💯 **ReactQuill v2** + +ReactQuill 2 is here, baby! And it brings a full port to TypeScript and React 16+, a refactored build system, and a general tightening of the internal logic. + +We worked hard to avoid introducing any behavioral changes. For the vast majority of the cases, no migration is necessary at all. However, support for long-deprecated props, the ReactQuill Mixin, and the Toolbar component have been removed. Be sure to read the [migration guide](#upgrading-to-reactquill-v2). -Special thank you to everyone who contributed during the 1.0.0 release cycle! +We expect this release to be a drop-in upgrade – if that isn't the case, please [file an issue](/../../issues/new) with the `v2` label. + +--- ## Quick Start -### Import the component +### With webpack or create-react-app -```jsx -import ReactQuill from 'react-quill'; // ES6 -import * as ReactQuill from 'react-quill'; // Typescript -const ReactQuill = require('react-quill'); // CommonJS +Make sure you have `react` and `react-dom`, and some way to load styles, like [style-loader](https://www.npmjs.com/package/style-loader). See the documentation on [themes](#themes) for more information. + +```sh +npm install react-quill --save ``` -### Import the stylesheet +```jsx +import React, { useState } from 'react'; +import ReactQuill from 'react-quill'; +import 'react-quill/dist/quill.snow.css'; -_Two common examples are shown below. How stylesheets are included in your app depends on build system (Webpack, SCSS, LESS, etc). See the documentation on [Themes](#theme) for more information._ +function MyComponent() { + const [value, setValue] = useState(''); -#### Fetching styles from the CDN + return ; +} +``` + +### With the browser bundle ```html - + ``` -#### Using `css-loader` with Webpack or `create-react-app` - -```jsx -require('react-quill/dist/quill.snow.css'); // CommonJS -import 'react-quill/dist/quill.snow.css'; // ES6 +```html + + + + + ``` -### Use the component +## Usage -```jsx -class MyComponent extends React.Component { - constructor(props) { - super(props) - this.state = { text: '' } // You can also pass a Quill Delta here - this.handleChange = this.handleChange.bind(this) - } +### Controlled mode caveats - handleChange(value) { - this.setState({ text: value }) - } +In controlled mode, components are supposed to prevent local stateful changes, and instead only have them happen through `onChange` and `value`. - render() { - return ( - - ) - } -} -``` +Because Quill handles its own changes, and does not allow preventing edits, ReactQuill has to settle for a hybrid between controlled and uncontrolled mode. It can't prevent the change, but will still override the content whenever `value` differs from current state. + +If you frequently need to manipulate the DOM or use the [Quill API](https://quilljs.com/docs/api/)s imperatively, you might consider switching to fully uncontrolled mode. ReactQuill will initialize the editor using `defaultValue`, but won't try to reset it after that. The `onChange` callback will still work as expected. + +Read more about uncontrolled components in the [React docs](https://facebook.github.io/react/docs/uncontrolled-components.html#default-values). ### Using Deltas @@ -106,38 +122,35 @@ Note that switching `value` from an HTML string to a Delta, or vice-versa, will ⚠️ Do not use the `delta` object you receive from the `onChange` event as `value`. This object does not contain the full document, but only the last modifications, and doing so will most likely trigger an infinite loop where the same changes are applied over and over again. Use `editor.getContents()` during the event to obtain a Delta of the full document instead. ReactQuill will prevent you from making such a mistake, however if you are absolutely sure that this is what you want, you can pass the object through `new Delta()` again to un-taint it. -### Controlled vs Uncontrolled Mode +### Themes -Pass `defaultValue` instead of `value` if you need to use DOM or [Quill API](https://quilljs.com/docs/api/)s to imperatively manipulate the editor state. -In this "uncontrolled" mode ReactQuill uses the prop as the initial value but allows the element to deviate after that. The `onChange` callback still works normally. +The Quill editor supports [themes](http://quilljs.com/docs/themes/). It includes a full-fledged theme, called _snow_, that is Quill's standard appearance, and a _bubble_ theme that is similar to the inline editor on Medium. At the very least, the _core_ theme must be included for modules like toolbars or tooltips to work. -- Read more about uncontrolled components in the [React docs][defaultvalues]. -- Read more about the available [props](#props). +To activate a theme, pass the name of the theme to the `theme` [prop](#props). Pass a falsy value (eg. `null`) to use the core theme. -[defaultvalues]: https://facebook.github.io/react/docs/uncontrolled-components.html#default-values - -## Options +```jsx + +``` -### Theme +Then, import the stylesheet for the themes you want to use. -The Quill editor supports [themes](http://quilljs.com/docs/themes/). It includes a full-fledged theme, called _snow_, that is Quill's standard appearance, a _bubble_ theme that is similar to the inline editor on Medium, and a _core_ theme containing only the bare essentials to allow modules like toolbars or tooltips to work. +This may vary depending how application is structured, directories or otherwise. For example, if you use a CSS pre-processor like SASS, you may want to import that stylesheet inside your own. These stylesheets can be found in the Quill distribution, but for convenience they are also linked in ReactQuill's `dist` folder. -These stylesheets can be found in the Quill distribution, but for convenience they are also linked in React Quill's `dist` folder. In a common case you would activate a theme by setting the theme [prop](#props). Pass a falsy value (`null`) to disable the theme. +Here's an example using [style-loader](https://www.npmjs.com/package/style-loader) for Webpack, or `create-react-app`, that will automatically inject the styles on the page: ```jsx - // or "bubble", null to use minimal core theme +import 'react-quill/dist/quill.snow.css'; ``` -And then link the appropriate stylesheet (only link the CSS for the themes you want to use): +The styles are also available via CDN: ```html - - - + ``` -This may vary depending how application is structured, directories or otherwise. For example, if you use a CSS pre-processor like SASS, you may want to import that stylesheet inside your own. - ### Custom Toolbar #### Default Toolbar Elements @@ -204,16 +217,16 @@ See this example live on Codepen: [Custom Toolbar Example](https://codepen.io/al * Custom "star" icon for the toolbar using an Octicon * https://octicons.github.io */ -const CustomButton = () => +const CustomButton = () => ; /* * Event handler to be attached using Quill toolbar module * http://quilljs.com/docs/modules/toolbar/ */ -function insertStar () { - const cursorPosition = this.quill.getSelection().index - this.quill.insertText(cursorPosition, "★") - this.quill.setSelection(cursorPosition + 1) +function insertStar() { + const cursorPosition = this.quill.getSelection().index; + this.quill.insertText(cursorPosition, '★'); + this.quill.setSelection(cursorPosition + 1); } /* @@ -221,7 +234,11 @@ function insertStar () { */ const CustomToolbar = () => (
- e.persist()} + > @@ -241,20 +258,20 @@ const CustomToolbar = () => (
-) +); /* * Editor component with custom toolbar and content containers */ class Editor extends React.Component { - constructor (props) { - super(props) - this.state = { editorHtml: '' } - this.handleChange = this.handleChange.bind(this) + constructor(props) { + super(props); + this.state = { editorHtml: '' }; + this.handleChange = this.handleChange.bind(this); } - handleChange (html) { - this.setState({ editorHtml: html }); + handleChange(html) { + this.setState({ editorHtml: html }); } render() { @@ -267,7 +284,7 @@ class Editor extends React.Component { modules={Editor.modules} /> - ) + ); } } @@ -277,38 +294,48 @@ class Editor extends React.Component { */ Editor.modules = { toolbar: { - container: "#toolbar", + container: '#toolbar', handlers: { - "insertStar": insertStar, - } - } -} + insertStar: insertStar, + }, + }, +}; /* * Quill editor formats * See http://quilljs.com/docs/formats/ */ Editor.formats = [ - 'header', 'font', 'size', - 'bold', 'italic', 'underline', 'strike', 'blockquote', - 'list', 'bullet', 'indent', - 'link', 'image', 'color', -] + 'header', + 'font', + 'size', + 'bold', + 'italic', + 'underline', + 'strike', + 'blockquote', + 'list', + 'bullet', + 'indent', + 'link', + 'image', + 'color', +]; /* * PropType validation */ Editor.propTypes = { placeholder: React.PropTypes.string, -} +}; /* * Render component on page */ ReactDOM.render( - , + , document.querySelector('.app') -) +); ``` @@ -324,11 +351,10 @@ The component has two types of formats: Example Code ```js -const ReactQuill = require('react-quill'); // CommonJS import ReactQuill, { Quill } from 'react-quill'; // ES6 +const ReactQuill = require('react-quill'); // CommonJS ``` - ```jsx /* * Example Parchment format from @@ -336,24 +362,24 @@ import ReactQuill, { Quill } from 'react-quill'; // ES6 * See the video example in the guide for a complex format */ let Inline = Quill.import('blots/inline'); -class BoldBlot extends Inline { } +class BoldBlot extends Inline {} BoldBlot.blotName = 'bold'; BoldBlot.tagName = 'strong'; Quill.register('formats/bold', BoldBlot); -const formats = ["bold"] // add custom format name + any built-in formats you need +const formats = ['bold']; // add custom format name + any built-in formats you need /* * Editor component with default and custom formats */ class MyComponent extends React.Component { constructor(props) { - this.formats = formats - this.state = { text: '' } + this.formats = formats; + this.state = { text: '' }; } handleChange(value) { - this.setState({text: value}) + this.setState({ text: value }); } render() { @@ -363,7 +389,7 @@ class MyComponent extends React.Component { onChange={this.handleChange} formats={this.formats} /> - ) + ); } } ``` @@ -394,164 +420,43 @@ class MyComponent extends React.Component { -### Mixin - -The module exports a mixin which can be used to create custom editor components. (Note that mixins will be deprecated in a future version of React). - -
-Example Code - -The ReactQuill default component is built using the mixin. See [component.js](src/component.js) for source. - -```jsx -import {Mixin} from 'react-quill' - -var MyComponent = React.createClass({ - mixins: [ ReactQuill.Mixin ], - - componentDidMount: function() { - var editor = this.createEditor( - this.getEditingArea(), - this.getEditorConfig() - ); - this.setState({ editor:editor }); - }, - - componentWillReceiveProps: function(nextProps) { - if ('value' in nextProps && nextProps.value !== this.props.value) { - this.setEditorContents(this.state.editor, nextProps.value); - } - }, - -}); -``` - -
- -## Upgrading to React-Quill v1.0.0 - -In most cases, ReactQuill will raise useful warnings to help you perform any necessary migration steps. - -Please note that many [migration steps to Quill v1.0](http://quilljs.com/guides/upgrading-to-1-0/) may also apply. - -
-Expand Upgrade Guide - -### The toolbar module - -With v1.0.0, Quill adopted a new [toolbar configuration format](https://quilljs.com/docs/modules/toolbar/), to which React Quill will delegates all toolbar functionality, and which is now the preferred way to customize the toolbar. - -Previously, toolbar properties could be set by passing a `toolbar` prop to React Quill. Pass the same options as `modules.toolbar` instead. - -
-Read More - -```diff -+ modules: { - toolbar: [ - ... - ], -+ }, - - -``` - -If you used to provide your own HTML toolbar component, you can still do the same: - -```diff -+ modules: { -+ toolbar: '#my-toolbar-component', -+ }, - - -``` - -Note that it is not possible to pass a toolbar component as a child to ReactQuill anymore. - -Previously, React Quill would create a custom HTML toolbar for you if you passed a configuration object as the `toolbar` prop. This will not happen anymore. You can still create a `ReactQuill.Toolbar` explicitly: - -```diff -+ modules: { -+ toolbar: '#my-quill-toolbar', -+ }, - -+ - - -``` - -However, consider switching to the new Quill format instead, or provide your own [toolbar component](#html-toolbar). - -React Quill now follows the Quill toolbar format closely. See the [Quill toolbar documentation](https://quilljs.com/docs/modules/toolbar/) for a complete reference on all supported options. - -
- -### Custom editing areas and refs +## Upgrading to ReactQuill v2 -Previously, to provide a custom element for Quill to mount on, it was necessary to pass a child identified by a specific `ref`: `editor`. +Upgrading to ReactQuill v2 should be as simple as updating your dependency. However, it also removes support for long-deprecated props, the ReactQuill Mixin, and the Toolbar component. -This is now unnecessary, so you can omit the `ref` entirely if you don't need it. In addition, any `ref` you keep won't be stolen from the owner component anymore. +### Deprecated props -Note, however, that React Quill will now ensure that the element is compatible with Quill. This means that passing a `