1 | <p align="center">
|
2 | <a href="http://draftjs.org/">
|
3 | <img src="https://draftjs.org/img/draftjs-logo.svg" alt="draftjs-logo" width="8%" />
|
4 | </a>
|
5 | </p>
|
6 | <h1 align="center">
|
7 | Draft.js
|
8 | </h1>
|
9 | <p align="center">
|
10 | <a href="https://travis-ci.org/facebook/draft-js">
|
11 | <img src="https://img.shields.io/travis/facebook/draft-js/master.svg?style=flat" alt="Build Status" />
|
12 | </a>
|
13 | <a href="https://yarn.pm/draft-js">
|
14 | <img src="https://img.shields.io/npm/v/draft-js.svg?style=flat" alt="npm version" />
|
15 | </a>
|
16 | </p>
|
17 | <p align="center">
|
18 | <img src="https://media.giphy.com/media/XHUjaxELpc11SiRSqN/giphy.gif" alt="Live Demo" />
|
19 | </p>
|
20 |
|
21 | --------------------
|
22 |
|
23 | Draft.js is a JavaScript rich text editor framework, built for React and
|
24 | backed by an immutable model.
|
25 |
|
26 | - **Extensible and Customizable:** We provide the building blocks to enable
|
27 | the creation of a broad variety of rich text composition experiences, from
|
28 | basic text styles to embedded media.
|
29 | - **Declarative Rich Text:** Draft.js fits seamlessly into
|
30 | [React](http://facebook.github.io/react/) applications,
|
31 | abstracting away the details of rendering, selection, and input behavior with a
|
32 | familiar declarative API.
|
33 | - **Immutable Editor State:** The Draft.js model is built
|
34 | with [immutable-js](https://facebook.github.io/immutable-js/), offering
|
35 | an API with functional state updates and aggressively leveraging data persistence
|
36 | for scalable memory usage.
|
37 |
|
38 | [Learn how to use Draft.js in your own project.](https://draftjs.org/docs/getting-started/)
|
39 |
|
40 | ## API Notice
|
41 |
|
42 | Before getting started, please be aware that we recently changed the API of
|
43 | Entity storage in Draft. The latest version, `v0.10.0`, supports both the old
|
44 | and new API. Following that up will be `v0.11.0` which will remove the old API.
|
45 | If you are interested in helping out, or tracking the progress, please follow
|
46 | [issue 839](https://github.com/facebook/draft-js/issues/839).
|
47 |
|
48 | ## Getting Started
|
49 |
|
50 | ```
|
51 | npm install --save draft-js react react-dom
|
52 |
|
53 | or
|
54 |
|
55 | yarn add draft-js react react-dom
|
56 | ```
|
57 |
|
58 | Draft.js depends on React and React DOM which must also be installed.
|
59 |
|
60 | ### Using Draft.js
|
61 |
|
62 | ```javascript
|
63 | import React from 'react';
|
64 | import ReactDOM from 'react-dom';
|
65 | import {Editor, EditorState} from 'draft-js';
|
66 |
|
67 | class MyEditor extends React.Component {
|
68 | constructor(props) {
|
69 | super(props);
|
70 | this.state = {editorState: EditorState.createEmpty()};
|
71 | this.onChange = (editorState) => this.setState({editorState});
|
72 | this.setEditor = (editor) => {
|
73 | this.editor = editor;
|
74 | };
|
75 | this.focusEditor = () => {
|
76 | if (this.editor) {
|
77 | this.editor.focus();
|
78 | }
|
79 | };
|
80 | }
|
81 |
|
82 | componentDidMount() {
|
83 | this.focusEditor();
|
84 | }
|
85 |
|
86 | render() {
|
87 | return (
|
88 | <div style={styles.editor} onClick={this.focusEditor}>
|
89 | <Editor
|
90 | ref={this.setEditor}
|
91 | editorState={this.state.editorState}
|
92 | onChange={this.onChange}
|
93 | />
|
94 | </div>
|
95 | );
|
96 | }
|
97 | }
|
98 |
|
99 | const styles = {
|
100 | editor: {
|
101 | border: '1px solid gray',
|
102 | minHeight: '6em'
|
103 | }
|
104 | };
|
105 |
|
106 | ReactDOM.render(
|
107 | <MyEditor />,
|
108 | document.getElementById('container')
|
109 | );
|
110 | ```
|
111 |
|
112 | Since the release of React 16.8, you can use [Hooks](https://reactjs.org/docs/hooks-intro.html) as a way to work with `EditorState` without using a class.
|
113 |
|
114 |
|
115 | ```js
|
116 | import React from 'react';
|
117 | import ReactDOM from 'react-dom';
|
118 | import {Editor, EditorState} from 'draft-js';
|
119 |
|
120 | function MyEditor() {
|
121 | const [editorState, setEditorState] = React.useState(
|
122 | EditorState.createEmpty()
|
123 | );
|
124 |
|
125 | const editor = React.useRef(null);
|
126 |
|
127 | function focusEditor() {
|
128 | editor.current.focus();
|
129 | }
|
130 |
|
131 | React.useEffect(() => {
|
132 | focusEditor()
|
133 | }, []);
|
134 |
|
135 | return (
|
136 | <div onClick={focusEditor}>
|
137 | <Editor
|
138 | ref={editor}
|
139 | editorState={editorState}
|
140 | onChange={editorState => setEditorState(editorState)}
|
141 | />
|
142 | </div>
|
143 | );
|
144 | }
|
145 |
|
146 | ```
|
147 |
|
148 | Note that the editor itself is only as tall as its contents. In order to give users a visual cue, we recommend setting a border and a minimum height via the `.DraftEditor-root` CSS selector, or using a wrapper div like in the above example.
|
149 |
|
150 | Because Draft.js supports unicode, you must have the following meta tag in the `<head>` `</head>` block of your HTML file:
|
151 |
|
152 | ```html
|
153 | <meta charset="utf-8" />
|
154 | ```
|
155 | Further examples of how Draft.js can be used are provided below.
|
156 |
|
157 | ### Examples
|
158 |
|
159 | Visit http://draftjs.org/ to try out a basic rich editor example.
|
160 |
|
161 | The repository includes a variety of different editor examples to demonstrate
|
162 | some of the features offered by the framework.
|
163 |
|
164 | To run the examples, first build Draft.js locally. The Draft.js build is tested
|
165 | with Yarn v1 only. If you're using any other package manager and something doesn't
|
166 | work, try using yarn v1:
|
167 |
|
168 | ```
|
169 | git clone https://github.com/facebook/draft-js.git
|
170 | cd draft-js
|
171 | yarn install
|
172 | yarn run build
|
173 | ```
|
174 |
|
175 | then open the example HTML files in your browser.
|
176 |
|
177 | Draft.js is used in production on Facebook, including status and
|
178 | comment inputs, [Notes](https://www.facebook.com/notes/), and
|
179 | [messenger.com](https://www.messenger.com).
|
180 |
|
181 | ## Browser Support
|
182 |
|
183 | | ![IE / Edge](https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_32x32.png) <br /> IE / Edge | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_32x32.png) <br /> Firefox | ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_32x32.png) <br /> Chrome | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_32x32.png) <br /> Safari | ![iOS Safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari-ios/safari-ios_32x32.png) <br />iOS Safari | ![Chrome for Android](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_32x32.png) <br/> Chrome for Android |
|
184 | | --------- | --------- | --------- | --------- | --------- | --------- |
|
185 | | IE11, Edge [1, 2]| last 2 versions| last 2 versions| last 2 versions| not fully supported [3] | not fully supported [3]
|
186 |
|
187 | [1] May need a shim or a polyfill for some syntax used in Draft.js ([docs](https://draftjs.org/docs/advanced-topics-issues-and-pitfalls/#polyfills)).
|
188 |
|
189 | [2] IME inputs have known issues in these browsers, especially Korean ([docs](https://draftjs.org/docs/advanced-topics-issues-and-pitfalls/#ime-and-internet-explorer)).
|
190 |
|
191 | [3] There are known issues with mobile browsers, especially on Android ([docs](https://draftjs.org/docs/advanced-topics-issues-and-pitfalls/#mobile-not-yet-supported)).
|
192 |
|
193 | ## Resources and Ecosystem
|
194 |
|
195 | Check out this curated list of articles and open-sourced projects/utilities: [Awesome Draft-JS](https://github.com/nikgraf/awesome-draft-js).
|
196 |
|
197 | ## Discussion and Support
|
198 |
|
199 | Join our [Slack team](https://draftjs.herokuapp.com)!
|
200 |
|
201 | ## Contribute
|
202 |
|
203 | We actively welcome pull requests. Learn how to
|
204 | [contribute](https://github.com/facebook/draft-js/blob/master/CONTRIBUTING.md).
|
205 |
|
206 | ## License
|
207 |
|
208 | Draft.js is [MIT licensed](https://github.com/facebook/draft-js/blob/master/LICENSE).
|
209 |
|
210 | Examples provided in this repository and in the documentation are separately
|
211 | licensed.
|