react-codemirror2
demo @ scniro.github.io/react-codemirror2
Install
npm install react-codemirror2 codemirror --save
react-codemirror2
ships with the notion of an uncontrolled and controlled component. UnControlled
consists of a simple wrapper largely powered by the inner workings of codemirror
itself, while Controlled
will demand state management from the user, preventing codemirror changes unless properly handled via value
. The latter will offer more control and likely be more appropriate with redux heavy apps.
uncontrolled usage
import {UnControlled as CodeMirror} from 'react-codemirror2'
<CodeMirror
value='<h1>I ♥ react-codemirror2</h1>'
options={{
mode: 'xml',
theme: 'material',
lineNumbers: true
}}
onChange={(editor, data, value) => {
}}
/>
controlled usage
import {Controlled as CodeMirror} from 'react-codemirror2'
<CodeMirror
value={this.state.value}
options={options}
onBeforeChange={(editor, data, value) => {
this.setState({value});
}}
onChange={(editor, data, value) => {
}}
/>
requiring codemirror resources
codemirror
comes as a peer dependency, meaning you'll need to require it in your project in addition to react-codemirror2
. This prevents any versioning conflicts that would arise if codemirror
came as a dependency through this wrapper. It's been observed that version mismatches can cause difficult to trace issues such as syntax highlighting disappearing without any explicit errors/warnings
Since codemirror ships mostly unconfigured, the user is left with the responsibility for requiring any additional resources should they be necessary. This is often the case when specifying certain language modes and themes. How to import/require these assets will vary according to the specifics of your development environment. Below is a sample to include the assets necessary to specify a mode of xml
(HTML) and a material
theme.
note that the base codemirror.css file is required in all use cases
@import 'codemirror/lib/codemirror.css';
@import 'codemirror/theme/material.css';
import CodeMirror from 'react-codemirror2';
require('codemirror/mode/xml/xml');
require('codemirror/mode/javascript/javascript');
props
| prop | type default
| components | description |
|--------------|------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| autoCursor
| boolean true
| Controlled
UnControlled
| should component cursor position correct when value
changed | |
| autoScroll
| boolean true
| Controlled
UnControlled
| should component scroll cursor position into view when value
changed |
| className
| string | Controlled
UnControlled
| pass through class class="react-codemirror2 className"
|
| defineMode
| object | Controlled
UnControlled
| pass a custom mode via {name: 'custom', fn: myModeFn}
|
| detach
| boolean | UnControlled
| should component ignore new props |
| options
| object | Controlled
UnControlled
| codemirror configuration |
| value
| string | *Controlled
UnControlled
| * component value must be managed for controlled components |
props cont. (wrapped codemirror programming api)
will programmatically set cursor to the position specified
<CodeMirror
[...]
cursor={{
line: 5,
ch: 10
}}
onCursor={(editor, data) => {}}
/>
will programmatically scroll to the specified coordinate
<CodeMirror
[...]
scroll={{
x: 50,
y: 50
}}
onScroll={(editor, data) => {}}
/>
selection={{ranges: array<{anchor, head}>, focus?: boolean}
- setSelections
will programmatically select the ranges specified
<CodeMirror
[...]
selection={{
ranges: [{
anchor: {ch: 8, line: 5},
head: {ch: 37, line: 5}
}],
focus: true // defaults false if not specified
}}
onSelection={(editor, data) => {}}
/>
events
| event | components | description |
|------------------------------------------------------------------|----------------------------------|-------------------------------------------------------------------------------------------------------------|
| editorDidAttach(editor) | UnControlled
| component is now responding to new props |
| editorDidConfigure(editor) | Controlled
UnControlled
| component configuration has been set |
| editorDidDetach(editor) | UnControlled
| component is now ignoring new props |
| editorDidMount(editor, [next]) | Controlled
UnControlled
| * invoking optional next
will trigger editorDidConfigure
|
| editorWillUnmount(editor) | Controlled
UnControlled
| invoked before componentWillUnmount
|
| onBeforeChange(editor, data, value, [next]) | Controlled
UnControlled
| * if used, next
is returned via UnControlled
and must be invoked to trigger onChange |
| onChange(editor, data, value) | Controlled
UnControlled
| the component value has been changed |
onBlur(editor, event)
- blur
onContextMenu(editor, event)
- contextmenu
onCopy(editor)
- copy
onCursor(editor, data)
- cursorActivity
onCursorActivity(editor)
- cursorActivity
onCut(editor)
- cut
onDblClick(editor, event)
- dblclick
onDragEnter(editor, event)
- dragenter
onDragOver(editor, event)
- dragover
onDragLeave(editor, event)
- dragleave
onDragStart(editor, event)
- dragstart
onDrop(editor, event)
- drop
onFocus(editor, event)
- focus
onGutterClick(editor, lineNumber, gutter, event)
- gutterClick
onInputRead(editor, changeObj)
- gutterClick
onKeyDown(editor, event)
- keydown
onKeyHandled(editor, key, event)
- keyhandled
onKeyPress(editor, event)
- keypress
onKeyUp(editor, event)
- keyup
onMouseDown(editor, event)
- mousedown
onPaste(editor)
- paste
onScroll(editor, data)
- scroll
onSelection(editor, data)
- beforeSelectionChange
onTouchStart(editor, event)
- touchstart
onUpdate(editor, event)
- update
onViewportChange(editor, from, to)
- viewportChange
FAQ
- Is server side rendering supported?
Yes. react-codemirror2 will prevent rendering in absence of navigator
. You can also force the component to not render via a PREVENT_CODEMIRROR_RENDER
global.
- How can I get the instance?
The recommended technique to get the instance is to persist the editor
returned via event callbacks. There is no static method to get it on demand, e.g. CodeMirror.getInstance()
. Example...
constructor() {
this.instance = null;
}
render() {
<CodeMirror editorDidMount={editor => { this.instance = editor }}/>
}
- How can I have a resizable editor?
Check out bokuweb/re-resizable. Wrapping your component with <Resizable/>'s
works well
Contributing
Pull Requests are welcome. Be mindful of the available scripts below to help submitting a well-received contribution.
npm run start
to run the app on localhost:8000
npm run test
to ensure tests continue to pass
npm run build
to generate the demo bundle
note that it's necessary to bump the package.json version prior to final npm run build
so we can grab the proposed new version as seen in the demo header. Also note, the core changes are to be made in src/index.tsx
as ./index.js
and ./index.d.ts
are generated
MIT © 2020 scniro