{"id":15039819,"url":"https://github.com/automattic/isolated-block-editor","last_synced_at":"2025-05-16T13:07:25.496Z","repository":{"id":37474133,"uuid":"341603787","full_name":"Automattic/isolated-block-editor","owner":"Automattic","description":"Repackages Gutenberg's editor playground as a full-featured multi-instance editor that does not require WordPress.","archived":false,"fork":false,"pushed_at":"2024-03-21T08:31:17.000Z","size":27846,"stargazers_count":369,"open_issues_count":38,"forks_count":58,"subscribers_count":27,"default_branch":"trunk","last_synced_at":"2025-05-15T16:05:41.581Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Automattic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-23T15:41:54.000Z","updated_at":"2025-05-12T20:56:45.000Z","dependencies_parsed_at":"2024-03-16T21:59:07.983Z","dependency_job_id":"b2041473-e92c-41e2-8269-958d55e5c0dc","html_url":"https://github.com/Automattic/isolated-block-editor","commit_stats":{"total_commits":480,"total_committers":21,"mean_commits":"22.857142857142858","dds":0.5645833333333333,"last_synced_commit":"fca1871c106f68f3926c479afda6b0aa1c6551a0"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fisolated-block-editor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fisolated-block-editor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fisolated-block-editor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automattic%2Fisolated-block-editor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Automattic","download_url":"https://codeload.github.com/Automattic/isolated-block-editor/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535829,"owners_count":22087399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T20:43:52.574Z","updated_at":"2025-05-16T13:07:25.471Z","avatar_url":"https://github.com/Automattic.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Isolated Block Editor\n\nRepackages Gutenberg's editor playground as a full-featured multi-instance editor that does not require WordPress.\n\nThe key features are:\n- Extends the Gutenberg playground editor to match a full editor\n- Allows multiple onscreen instances with seperate data stores and keyboard handlers\n- Undo history\n\nAnd a full list of features:\n\n- Dynamic switching of data stores for compatability with third-party blocks\n- Works at sizes smaller than full screen\n- Block allow and disallow list, per instance\n- Preferences (saved to localStorage) and options (saved to memory), per instance\n- Overriding of key Gutenberg store functions\n- Patterns, reusable blocks, groups, and template support\n- Block inserter in a popover\n- Block inspector in a popover\n- Built in toolbar with options for displaying a more menu, block inspector, and block buttons\n- Fullscreen mode (requires additional CSS)\n- Preview mode (requires additional CSS and JS)\n- Visual \u0026 code editor\n- PHP (WordPress) code to load the editor outside of wp-admin\n- Menu for custom links\n- Re-routing of WordPress API requests\n\nThe Isolated Block Editor is provided in three forms:\n- ES6 module\n- CommonJS module\n- Standalone JavaScript file, for inclusion on any browser page\n\nThis library only works with the specific versions of Gutenberg listed below.\n\nRequires: Gutenberg 16.9\n\nExamples:\n- [Plain Text Editor](https://github.com/Automattic/isolated-block-editor/blob/trunk/src/browser/README.md) - standalone JS and CSS file that can replace any `textarea` on any page with a full Gutenberg editor\n- [Blocks Everywhere](https://github.com/Automattic/blocks-everywhere/) - a WordPress plugin to add Gutenberg to comments, WP admin pages, bbPress, and BuddyPress\n- [Gutenberg Chrome Extension](https://github.com/Automattic/gutenberg-everywhere-chrome/) - a Chrome extension that allows Gutenberg to be used on any page\n- [Gutenberg Desktop](https://github.com/Automattic/gutenberg-desktop/) - a desktop editor that supports the loading and saving of HTML and Markdown files\n- [P2](https://wordpress.com/p2/) - WordPress as a collaborative workspace (coming soon for self-hosted)\n- Editor Block - a block that allows an editor to be added to a page (coming soon)\n\nDo you use this in your own project? Let us know!\n\n## Why would I use this?\n\nGutenberg already provides a playground which allows it to be used outside of WordPress. This is actually used as the basis for the Isolated Block Editor.\n\nHowever, it provides a limited set of features, and extending it further into a usable editor can take some effort. For example, it doesn't include any undo history.\n\nThe Isolated Block Editor is a full editor that handles a lot of these complexities. It should not be considered a replacement for the Gutenberg playground, but more of an opinionated layer on top.\n\nThis should be considered experimental, and subject to changes.\n\n## Bundling and WordPress\n\nThe Isolated Block Editor aims to provide an editor that is as isolated from WordPress as possible. However, it can still be used on a WordPress site, and the decision comes down to the bundling:\n\n- Bundled without Gutenberg - if used on a WordPress site then you can use the Gutenberg code already included with WordPress. You will need a working WordPress site, but do not need to include Gutenberg within your editor\n- Bundled with Gutenberg - Gutenberg is included within the editor and there is no dependency on WordPress or PHP\n\nExamples are provided for both situations (see [Plain text editor](examples/plain-text-editor/README.md) for bundled and [Blocks Everywhere](https://github.com/Automattic/gutenberg-everywhere/) for unbundled).\n\nThe key difference is in the Webpack config. If you don't want to bundle Gutenberg with your editor then you can use the `DependencyExtractionWebpackPlugin` plugin:\n\n```js\nplugins: [\n\tnew DependencyExtractionWebpackPlugin( { injectPolyfill: true } )\n]\n```\n\nAlternatively you can use the [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/packages/packages-scripts/) build system, which automatically runs `DependencyExtractionWebpackPlugin`:\n\n`wp-scripts start`\n\nYou can use the provided [`iso-gutenberg.php`](examples/wordpress-php/README.md) file to help when using the IsolatedBlockEditor on a WordPress site. It will load Gutenberg and set up your configuration.\n\n## Standalone Module\n\nYou can use the provided `isolated-block-editor.js`, `core.css`, and `isolated-block-editor.css` files on any web page, regardless of whether it is on WordPress. It will provide two global functions which can turn a `textarea` into a block editor. Here's an example:\n\n```js\n\u003cscript crossorigin src=\"https://unpkg.com/react@18/umd/react.production.min.js\"\u003e\u003c/script\u003e\n\u003cscript crossorigin src=\"https://unpkg.com/react-dom@18/umd/react-dom.production.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"isolated-block-editor.js\"\u003e\u003c/script\u003e\n\u003clink rel=\"stylesheet\" href=\"core.css\" /\u003e\n\u003clink rel=\"stylesheet\" href=\"isolated-block-editor.css\" /\u003e\n\n\u003cbody\u003e\n\t\u003ctextarea id=\"editor\"\u003e\u003c/textarea\u003e\n\n\t\u003cscript\u003e\n\t\twp.attachEditor( document.getElementById( 'editor' ) );\n\t\u003c/script\u003e\n\u003c/body\u003e\n\n```\n\nNote that you must load React before loading the editor.\n\nYou can find an example in [`src/browser/index.html`](src/browser/index.html).\n\n## CSS\n\nIf you are using on a WordPress site then WordPress will load the core Gutenberg CSS as part of the [`iso-gutenberg.php`](examples/wordpress-php/README.md) script.\n\nIf you are not using on a WordPress site then you will need to load the core CSS yourself. You can either do this by including the following modules and importing directly:\n\n- `@wordpress/components`\n- `@wordpress/block-editor`\n- `@wordpress/block-library`\n- `@wordpress/format-library`\n\n```scss\n@import '@wordpress/components/build-style/style.css';\n@import '@wordpress/block-editor/build-style/style.css';\n@import '@wordpress/block-library/build-style/style.css';\n@import '@wordpress/block-library/build-style/editor.css';\n@import '@wordpress/block-library/build-style/theme.css';\n@import '@wordpress/format-library/build-style/style.css';\n```\n\nAlternatively you can directly import the bundled `build-browser/core.css` CSS:\n\n```js\nimport '@automattic/isolated-block-editor/build-browser/core.css';\n```\n\n## Using\n\nThe module is currently only available on Github and can be added with:\n\n`npm install @automattic/isolated-block-editor@1.2.0 --save` (where `1.2.0` is the version you want to use)\n\n## Future\n\nThe code here deals with two kinds of problems:\n- Adding features to the Gutenberg playground - these are already provided by Gutenberg, but are packaged up here for you\n- Adding workarounds to Gutenberg - these are situations where Gutenberg doesn't provide a feature, or doesn't export a feature, and so a workaround is needed.\n\nIt is hoped that most of the workarounds can be migrated back to Gutenberg so that they are no longer needed. Sometimes these workarounds involve duplicating parts of Gutenberg, which is not ideal. It is possible that the Isolated Block Editor may no longer be needed as a seperate entity.\n\n## Development\n\nIf multiple editors are on-screen then the `IsolatedBlockEditor` will ensure that the `wp` global refers to the currently focussed instance. This should make it more compatible with plugins and third-party code that uses the `wp` global.\n\n### Usage\n\nInclude the `IsolatedBlockEditor` module and then create an instance:\n\n```js\n\nimport IsolatedBlockEditor from '@automattic/isolated-block-editor';\n\nrender(\n\t\u003cIsolatedBlockEditor\n\t\tsettings={ settings }\n\t\tonSaveContent={ ( html ) =\u003e saveContent( html ) }\n\t\tonLoad={ ( parse ) =\u003e loadInitialContent( parse ) }\n\t\tonError={ () =\u003e document.location.reload() }\n\t\u003e\n\t\u003c/IsolatedBlockEditor\u003e,\n\tdocument.querySelector( '#editor' )\n);\n```\n\nThe `IsolatedBlockEditor` also exports the following support components:\n\n- `EditorLoaded` - Include this to be notified when the editor is loading and has loaded\n- `DocumentSection` - Wrap up a component to appear in the document tab of the inspector\n- `ToolbarSlot` - Insert content into the toolbar\n- `FooterSlot` - Insert content into the footer\n- `EditorHeadingSlot` - Insert content at the beginning of the editor area. Suitable for titles.\n- `ActionArea` - Insert content into the actions sidebar\n\n```js\n\nimport IsolatedBlockEditor, { EditorLoaded, DocumentSection, ToolbarSlot } from 'isolated-block-editor';\n\nrender(\n\t\u003cIsolatedBlockEditor\n\t\tsettings={ settings }\n\t\tonSaveContent={ ( html ) =\u003e saveContent( html ) }\n\t\tonLoad={ ( parse ) =\u003e loadInitialContent( parse ) }\n\t\tonError={ () =\u003e document.location.reload() }\n\t\u003e\n\t\t\u003cEditorLoaded onLoaded={ () =\u003e {} } onLoading={ () =\u003e {} } /\u003e\n\t\t\u003cDocumentSection\u003eExtra Information\u003c/DocumentSection\u003e\n\n\t\t\u003cToolbarSlot\u003e\n\t\t\t\u003cbutton\u003eBeep!\u003c/button\u003e\n\t\t\u003c/ToolbarSlot\u003e\n\t\u003c/IsolatedBlockEditor\u003e,\n\tdocument.querySelector( '#editor' )\n);\n```\n\nThe following function is also provided:\n\n- `initializeEditor` - Call this to initialize the editor if it needs to be done before being used.\n\n### Props\n\n#### settings\n\n- _iso_ `[object]` - IsolatedBlockEditor settings object\n- _iso.preferencesKey_ `[string|null]` - Preferences key. Default to null to disable\n- _iso.defaultPreferences_ {object} - Default preferences\n- _iso.persistenceKey_ `[string|null]` - Persistence key. Default to null to disable\n- _iso.customStores_ `[array]` - Array of store objects, in a form suitable for passing to Gutenberg's `createReduxStore`\n- _iso.blocks_ `[object]` - Block restrictions\n- _iso.blocks.allowBlocks_ `[string[]]` - list of block names to allow, defaults to none\n- _iso.blocks.disallowBlocks_ `[string[]]` - list of block names to disallow, defaults to none\n- _iso.disallowEmbed_ `[string[]]`  - List of embed names to remove, defaults to none.\n- _iso.toolbar_ `[Object]` - Toolbar settings\n- _iso.toolbar.navigation_ `[boolean]` - Enable or disable the toolbar navigation button, defaults to `false`\n- _iso.toolbar.undo_ `[boolean]` - Enable or disable the toolbar undo/redo buttons, defaults to `true`\n- _iso.toolbar.documentInspector_ `[string|null]` - Set to a string to show as a new tab in the inspector and filled with `DocumentSection`, otherwise defaults to no new tab\n- _iso.sidebar_ `[Object]` - Sidebar settings\n- _iso.sidebar.inserter_ `[boolean]` - Enable or disable the sidebar block inserter, defaults to `true`\n- _iso.sidebar.inspector_ `[boolean]` - Enable or disable the sidebar block inspector, defaults to `false`\n- _iso.sidebar.customComponent_ `[function]` - A function returning a custom sidebar component, or null to uses the default sidebar\n- _iso.moreMenu_ `[Object]` - More menu settings\n- _iso.moreMenu.editor_ `[boolean]` - Enable or disable the editor sub menu (visual/code editing), defaults to `false`\n- _iso.moreMenu.fullscreen_ `[boolean]` - Enable or disable the fullscreen option, defaults to `false`\n- _iso.moreMenu.preview_ `[boolean]` - Enable or disable the preview option, defaults to `false`\n- _iso.moreMenu.topToolbar_ `[boolean]` - Enable or disable the 'top toolbar' option, defaults to `false`\n- _iso.linkMenu_ `[array]` - Link menu settings. Array of `title` and `url`, defaults to none\n- _iso.currentPattern_ `[string]` - The pattern to start with, defaults to none\n- _iso.allowApi_ `[boolean]` - Allow API requests, defaults to `false`\n\n- _editor_ `[object]` - Gutenberg settings object\n\nA settings object that contains all settings for the IsolatedBlockEditor, as well as for Gutenberg. Any settings not provided will use defaults.\n\nThe block allow and disallow list works as follows:\n- All blocks are allowed, unless the `allowBlocks` option is set which defines the list of allowed blocks\n- Anything in the `disallowBlocks` list is removed from the list of allowed blocks.\n\n#### onSaveContent\n\n- _content_ - content to be saved, as an HTML string\n\nSave callback that saves the content as an HTML string. Will be called for each change in the editor content.\n\n#### onSaveBlocks\n\n- _blocks_ `[Array]` - blocks to be saved\n- _ignoredContent_ `[Array]`- array of HTML strings of content that can be ignored\n\nSave callback that is supplied with a list of blocks and a list of ignored content. This gives more control than `onSaveContent`, and is used if you want to filter the saved blocks. For example,\nif you are using a template then it will appear in the `ignoredContent`, and you can then ignore the `onSaveBlocks` call if it matches the `blocks`.\n\n#### onLoad\n\n- _parse_ `[string]` - Gutenberg `parse` function that parses HTML as a string and returns blocks\n\nLoad the initial content into the editor. This is a callback that runs after the editor has been created, and is supplied with a `parse` function that is specific to this editor instance. This should\nbe used so that the appropriate blocks are available.\n\n#### __experimentalUndoManager\n\nAn alternative history undo/redo manager to be used by the editor. The passed in object must contain an `undo` and a `redo` methods, as well as a `undoStack` and a `redoStack` array properties containing the corresponding history. If not provided, the default history management will be used. This property is experimental and can change or be removed at any time.\n\n#### __experimentalOnInput\n\nAn optional callback that will be passed down to the Gutenberg editor if provided.This property is experimental and can change or be removed at any time.\n\n#### __experimentalOnChange\n\nAn optional callback that will be passed down to the Gutenberg editor if provided.This property is experimental and can change or be removed at any time.\n\n#### __experimentalValue\n\nAn optional value (blocks) for the editor to show. If provided, it will be used as the internal value/blocks to display.This property is experimental and can change or be removed at any time.\n\n#### __experimentalOnSelection\n\nAn optional callback that will be called when the selection changes in the editor. The only parameter passed to the callback will be the new selection value.\n\n#### onError\n\nCallback if an error occurs.\n\n#### className\n\nAdditional class name attached to the editor.\n\n#### renderMoreMenu\n\n- _menuSettings_ `[object]` - settings for this particular editor\n- _onClose_ `[func]` - Callback to close the more menu\n\nRender additional components in the more menu.\n\nNote: this needs improving or replacing with something more flexible\n\n#### children\n\nAdd any components to customise the editor. These components will have access to the editor's Redux store.\n\n#### Media uploader\n\nIf you want to make use of a media uploader and media library then you must set this up similar using the `editor.MediaUpload` filter. For example, if you want to use the Gutenberg media library then this would be:\n\n```js\nimport { MediaUpload } from '@wordpress/media-utils';\n\naddFilter( 'editor.MediaUpload', 'your-namespace/media-upload', () =\u003e MediaUpload );\n```\n\nYou will also need to pass in the media uploader as part of the editor settings:\n\n```js\nimport { mediaUpload } from '@wordpress/editor';\n\nconst settings = { your settings };\n\nsettings.editor.mediaUpload = mediaUpload;\n```\n\nIn versions earlier than 2.21.0 this was automatically done, but this meant that you were unable to modify or disable it.\n\n### Custom settings sidebar\n\nBy default the editor will use the Gutenberg settings sidebar. This provides the block and document inspector tabs, along with associated content.\n\nIf you wish to customise this sidebar then you can use the `iso.sidebar.customComponent` setting and pass a function that returns a React component.\n\nYou will need to manage the display of the sidebar yourself, including whether it should appear or not. It may help to look at the [existing sidebar code](src/components/block-editor/sidebar.js) for reference.\n\nFor example:\n\n```js\nsidebar: {\n\tcustomComponent: () =\u003e \u003cdiv\u003eMy custom sidebar\u003c/div\u003e\n},\n```\n\n### Extending\n\nCustom behaviour can be added through child components. These components will have access to the `isolated/editor` store, as well as to the editor instance versions of `core/block-editor`.\n\n### Gutenberg requirements\n\nGutenberg uses iframes to display various parts of the editor, and it uses the global `window.__editorAssets` to store styles and scripts that will be added to this iframe. You may need to also\nuse this.\n\nThe default is:\n\n`window.__editorAssets = { styles: '', scripts: '' }`\n\nThe values should be full `\u003clink\u003e` and `\u003cscript\u003e` tags.\n\n## Releasing\n\nTo make a release, ensure you are on the trunk branch. Do not update the version number in `package.json` - the release process will do this for you. Then run:\n\n`GITHUB_TOKEN=\u003cTOKEN\u003e yarn dist`\n\n## Common Problems\n\nIf Storybook complains about different ES6 problems then it can sometimes be solved with `npx yarn-deduplicate --scopes @babel`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautomattic%2Fisolated-block-editor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautomattic%2Fisolated-block-editor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautomattic%2Fisolated-block-editor/lists"}