monaco-react

# @monaco-editor/react · [](https://www.npmjs.com/package/@monaco-editor/react) [](https://github.com/suren-atoyan/monaco-react/blob/master/LICENSE) [](https://www.npmjs.com/package/@monaco-editor/react) [](https://github.com/suren-atoyan/monaco-react/pulls)

Monaco Editor for React · use the [monaco-editor](https://microsoft.github.io/monaco-editor/) in **any** [React](https://reactjs.org/) application without needing to use `webpack` (or `rollup`/`parcel`/etc) configuration files / plugins

---

- :white_check_mark: React `V19` support! - :keyboard: rewritten with `TypeScript` :fire: - :zap: [multi-model editor](#multi-model-editor) is already supported; enjoy it :tada: - :tada: version `v4` is here - to see what's new in the new version and how to migrate from `v3`, please read this [doc](./v4.changes.md) (also, if you need the old version `README`, it's [here](https://github.com/suren-atoyan/monaco-react/blob/v3.8.3/README.md)) - :video_game: the new section [Development / Playground](#development-playground) has been created - now you can run the playground and play with the internals of the library - :dizzy: it's already integrated with [@monaco-editor/loader](https://github.com/suren-atoyan/monaco-loader)

---

## Synopsis `Monaco` editor wrapper for easy/one-line integration with any `React` application without needing to use `webpack` (or any other module bundler) configuration files / plugins. It can be used with apps generated by `create-react-app`, `create-snowpack-app`, `vite`, `Next.js` or any other app generators - **you don't need to eject or rewire them**. ## Motivation The [monaco-editor](https://microsoft.github.io/monaco-editor/) is a well-known web technology based code editor that powers [VS Code](https://code.visualstudio.com/). This library handles the setup process of the `monaco-editor` and provides a clean `API` to interact with `monaco` from any `React` environment #### Demo [Check it out!](https://monaco-react.surenatoyan.com/) ## Documentation - [Installation](#installation) - [Introduction](#introduction) - [Usage](#usage) - [Simple usage](#simple-usage) - [Get value](#get-value) - [`editor instance`](#editor-instance) - [`monaco instance`](#monaco-instance) - [`useMonaco`](#usemonaco) - [`loader/config`](#loader-config) - [Multi-model editor](#multi-model-editor) - [`onValidate`](#onvalidate) - [Notes](#notes) - [For `electron` users](#for-electron-users) - [For `Next.js` users](#for-nextjs-users) - [Create your own editor!](#create-your-own-editor) - [Development / Playground](#development-playground) - [Props](#props) - [`Editor`](#editor) - [`Diff Editor`](#diffeditor) ### Installation ```bash npm install @monaco-editor/react # or @monaco-editor/react@next for React v19 ``` or ```bash yarn add @monaco-editor/react ``` or you can use `CDN`. [Here is an example](https://codesandbox.io/s/cdn-example-fnhfr?file=/index.html) **NOTE**: For `TypeScript` type definitions, this package uses the [monaco-editor](https://www.npmjs.com/package/monaco-editor) package as a peer dependency. So, if you need types and don't already have the [monaco-editor](https://www.npmjs.com/package/monaco-editor) package installed, you will need to do so ## Ask AI [Monaco-React](https://codeparrot.ai/oracle?owner=suren-atoyan&repo=monaco-react) AI will help you understand this repository better. You can ask for code examples, installation guide, debugging help and much more. ### Introduction Besides types, the library exports `Editor`and `DiffEditor` components, as well as the `loader` utility and the `useMonaco` hook: ```javascript import Editor, { DiffEditor, useMonaco, loader } from '@monaco-editor/react'; ``` ### Usage #### Simple usage Here is an example of a simple integration of `monaco` editor with a `React` project.
You just need to import and render the `Editor` component: ```javascript import React from 'react'; import ReactDOM from 'react-dom'; import Editor from '@monaco-editor/react'; function App() { return ; } const rootElement = document.getElementById('root'); ReactDOM.render(, rootElement); ``` [codesandbox](https://codesandbox.io/s/simple-usage-uyf5n?file=/src/App.js) Extended example ``` … ``` [codesandbox](https://codesandbox.io/s/simple-usage-extended-3ivw2?file=/src/App.js) #### Get value There are two options to get the current value: 1. get the current model value from the `editor` instance ``` … ``` [codesandbox](https://codesandbox.io/s/get-value-r9be5?file=/src/App.js) 2. get the current model value via `onChange` prop ```javascript import React from 'react'; import ReactDOM from 'react-dom'; import Editor from '@monaco-editor/react'; function App() { function handleEditorChange(value, event) { console.log('here is the current model value:', value); } return ( ); } const rootElement = document.getElementById('root'); ReactDOM.render(, rootElement); ``` [codesandbox](https://codesandbox.io/s/onchange-4nf6g?file=/src/App.js) (get the `DiffEditor` values via `editor` instance) ``` … ``` [codesandbox](https://codesandbox.io/s/get-values-diffeditor-c6xrg?file=/src/App.js) #### `editor instance` The `editor` instance is exposed from the `onMount` prop as a first parameter, the second is the `monaco` instance ``` … ``` [codesandbox](https://codesandbox.io/s/editor-instance-354cr?file=/src/App.js) #### `monaco instance` There are three options to get the `monaco` instance: 1. via `onMount/beforeMount` ``` … ``` [codesandbox](https://codesandbox.io/s/simple-usage-forked-il8kt?file=/src/App.js) 2. via `loader` utility ```javascript import { loader } from '@monaco-editor/react'; loader.init().then((monaco) => console.log('here is the monaco instance:', monaco)); ``` [codesandbox](https://codesandbox.io/s/monaco-instance-loader-ndzu9?file=/src/App.js) 3. via `useMonaco` hook ```javascript import React from 'react'; import ReactDOM from 'react-dom'; import Editor, { useMonaco } from '@monaco-editor/react'; function App() { const monaco = useMonaco(); useEffect(() => { if (monaco) { console.log('here is the monaco instance:', monaco); } }, [monaco]); return ; } const rootElement = document.getElementById('root'); ReactDOM.render(, rootElement); ``` [codesandbox](https://codesandbox.io/s/monaco-instance-usemonaco-88eml?file=/src/App.js) #### `useMonaco` `useMonaco` is a `React` hook that returns the instance of the `monaco`. But there is an important note that should be considered: the initialization process is being handled by the `loader` utility (the reference of [@monaco-editor/loader](https://github.com/suren-atoyan/monaco-loader)): that process is being done asynchronously and only once. So, if the first initiator of the initialization is `useMonaco` hook, the first returned value will be null, due to its asynchronous installation. Just check the returned value of `useMonaco` ``` … ``` [codesandbox](https://codesandbox.io/s/usemonaco-9rpc4) #### `loader-config` The library exports (named) the utility called `loader`. Basically, it's the reference of [@monaco-editor/loader](https://github.com/suren-atoyan/monaco-loader). By default, `monaco` files are being downloaded from `CDN`. There is an ability to change this behavior, and other things concerning the `AMD` loader of `monaco`. We have a default [config file](https://github.com/suren-atoyan/monaco-loader/blob/master/src/config/index.js) that you can modify by the way shown below: ```js import { loader } from '@monaco-editor/react'; // you can change the source of the monaco files loader.config({ paths: { vs: '...' } }); // you can configure the locales loader.config({ 'vs/nls': { availableLanguages: { '*': 'de' } } }); // or loader.config({ paths: { vs: '...', }, 'vs/nls': { availableLanguages: { '*': 'de', }, }, }); ``` ##### use `monaco-editor` as an npm package Starting from version `v4.4.0` it's possible to use `monaco-editor` as an `npm` package; import it from `node_modules` and include `monaco` sources into your bundle (instead of using CDN). To make it work you can do the following: ```javascript import * as monaco from 'monaco-editor'; import { loader } from '@monaco-editor/react'; loader.config({ monaco }); // ... ``` NOTE: you should be aware that this may require additional `webpack` plugins, like [monaco-editor-webpack-plugin](https://www.npmjs.com/package/monaco-editor-webpack-plugin) or it may be impossible to use in apps generated by [CRA](https://reactjs.org/) without ejecting them. If you use [Vite](https://vitejs.dev/), you need to do this: ``` … ``` [codesandbox](https://codesandbox.io/s/loader-ry1bb?file=/src/App.js) **NOTE**: your passed object will be deeply merged with the [default one](https://github.com/suren-atoyan/monaco-loader/blob/master/src/config/index.js) #### Multi-model editor When you render the `Editor` component, a default model is being created. It's important to mention that when you change the `language` or `value` props, they affect the same model that has been auto-created at the mount of the component. In most cases it's okay, but the developers face problems when they want to implement a multi-model editor to support tabs/files like in `IDE`s. And previously to handle multiple models they had to do it manually and out of the component. Now, the multi-model `API` is supported :tada: Let's check how it works. There are three parameters to create a model - `value`, `language` and `path` (`monaco.editor.createModel(value, language, monaco.Uri.parse(path))`). You can consider last one (`path`) as an identifier for the model. The `Editor` component, now, has a `path` prop. When you specify a `path` prop, the `Editor` component checks if it has a model by that path or not. If yes, the existing model will be shown, otherwise, a new one will be created (and stored). Using this technique you can correspond your files with paths, and create a fully multi-model editor. You can open your file, do some changes, choose another file, and when you come back to the first one the previous model will be shown with the whole view state, text selection, undo stack, scroll position, etc. ([simple demo](https://codesandbox.io/s/multi-model-editor-kugi6?file=/src/App.js)) Here is a simple example: let's imagine we have a `JSON` like representation of some file structure, something like this: ```javascript const files = { 'script.js': { name: 'script.js', language: 'javascript', value: someJSCodeExample, }, 'style.css': { name: 'style.css', language: 'css', value: someCSSCodeExample, }, 'index.html': { name: 'index.html', language: 'html', value: someHTMLCodeExample, }, }; ``` And here is our simple multi-model editor implementation: ``` … ``` The properties: - `defaultValue` - `defaultLanguage` - `defaultPath` - `value` - `language` - `path` - `saveViewState` will give you more flexibility in working with a multi-model editor. **NOTE** `defaultValue`, `defaultLanguage`, and `defaultPath` are being considered **only** during a new model creation
`value`, `language`, and `path` are being tracked the **whole time**
`saveViewState` is an indicator whether to save the models' view states between model changes or not [codesandbox](https://codesandbox.io/s/multi-model-editor-kugi6?file=/src/App.js) ####