Text editing with media widgets
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo onRequestLink; close #314 Jan 27, 2017
src changes & lint Feb 21, 2017
targets top margin when tip Sep 27, 2016
test Merge featureFlags from 1.4.x Jan 24, 2017
.babelrc Revert "WIP redux" Feb 9, 2016
.eslintrc eslint dangle Dec 16, 2016
.gitignore Merge featureFlags from 1.4.x Jan 24, 2017
.npmignore don't ignore dist widgets Jan 23, 2016
.travis.yml node v7.4.0 Jan 21, 2017
CHANGES.md changes & lint Feb 21, 2017
README.md simplify link:toggle flow #314 Jan 31, 2017
gh-pages.sh dist/.nojekyll for demo Jan 11, 2017
index.html disable tooltips #289 Sep 29, 2016
jsconfig.json update deps, add jsconfig Dec 7, 2015
karma.conf.js no browserstack May 19, 2016
package.json 2.1.3 Feb 21, 2017
webpack.config.js lint Jan 24, 2017


npm start


Build Status

Using ProseMirror with data from the Grid API

Demo: the-grid.github.io/ed/, with fixture

The demo shows translating from ProseMirror to the the Grid API JSON and back.


ProseMirror provides a high-level schema-based interface for interacting with contenteditable, taking care of that pain. Ed is focused on:

  • Schema to translate between the Grid API data and ProseMirror doc type
  • Coordinating widgets (block editors specialized by type) (example)


Using as a React ⚛ component

Ed exposes a React component by default.

import Ed from '@the-grid/ed'

export default class PostEditor extends React.Component {
  render() {
    return (
      <Ed key='item-uuid' initialContent={...} onChange={...} ... />

Using as a stand-alone library in iframe or similar

Including dist/build.js in your page exposes window.TheGridEd

<script src='dist/build.js'></script>

There are {mountApp, unmountApp} helper methods available to use like this:

  var container = document.querySelector('#ed')
  window.TheGridEd.mountApp(container, {
    // REQUIRED -- Content array from post
    initialContent: [],
    // OPTIONAL (default true) enable or disable the default menu
    menuBar: true,
    // REQUIRED -- Hit on every change
    onChange: function () {
      /* App can show "unsaved changes" in UI */
    onShareFile: function (index) {
      /* App triggers native file picker */
      /* App calls ed.insertPlaceholders(index, count) and gets array of ids back */
      /* App uploads files and sets status on placeholder blocks with ed.updateProgress */
      /* On upload / measurement finishing, app replaces placeholder blocks with ed.setContent */
    onRequestCoverUpload: function (id) {
      /* Similar to onShareFile, but hit with block id instead of index */
      /* App uploads files and sets status on blocks with ed.updateProgress */
      /* Once upload is complete, app hits ed.setCoverSrc */
    onShareUrl: function ({block, url}) {
      /* Ed made the placeholder with block id */
      /* App shares url with given block id */
      /* App updates status on placeholder blocks with ed.updateProgress */
      /* On share / measurement finishing, app replaces placeholder blocks with ed.setContent */
    onPlaceholderCancel: function (id) {
      /* Ed removed the placeholder if you call ed.getContent() now */
      /* App should cancel the share or upload */
    onRequestLink: function (value) {
        If defined, Ed will _not_ show prompt for link
        If selection is url-like, value will be the selected string
        App can then call `ed.execCommand('link:toggle', {href, title})`
          Note: If that is called while command 'link:toggle' is 'active', it will remove the link, not replace it
    onDropFiles: function (index, files) {
      /* App calls ed.insertPlaceholders(index, files.length) and gets array of ids back */
      /* App uploads files and sets status on placeholder blocks with ed.updateProgress */
      /* On upload / measurement finishing, app replaces placeholder blocks with ed.setContent */
    onDropFileOnBlock: function (id, file) {
      /* App uploads files and sets status on block with ed.updateProgress */
      /* Once upload is complete, app hits ed.setCoverSrc */
    onMount: function (mounted) {
      /* Called once PM and widgets are mounted */
      window.ed = mounted
    onCommandsChanged: function (commands) {
      /* Object with commandName keys and one of inactive, active, disabled */
    // OPTIONAL -- imgflo image proxy config
    imgfloConfig: {
      server: 'https://imgflo.herokuapp.com/',
      key: 'key',
      secret: 'secret'
    // OPTIONAL -- where iframe widgets live relative to app (or absolute)
    widgetPath: './node_modules/',
    // OPTIONAL -- site-wide settings to allow cover filter, crop, overlay; default true
    coverPrefs: {
      filter: false,
      crop: true,
      overlay: true
    // OPTIONAL -- site or user flags to reduce functionality
    featureFlags: {
      edCta: false,
      edEmbed: false
  // Returns array of inserted placeholder ids
  ed.insertPlaceholders(index, count)
  // Update placeholder metadata
  // {status (string), progress (number 0-100), failed (boolean)}
  // metadata argument with {progress: null} will remove the progress bar
  ed.updateProgress(id, metadata)
  // Once block cover upload completes
  // `cover` is object with {src, width, height}
  ed.setCover(id, cover)

  // For placeholder or media block with uploading cover
  // `src` should be blob: or data: url of a
  // sized preview of the local image
  ed.setCoverPreview(id, src)

  // Returns content array
  // Expensive, so best to debounce and not call this on every change
  // Above the fold block is index 0, and starred
  // Only inserts/updates placeholder blocks and converts placeholder blocks to media
  // Returns true if command applies successfully with current selection

Demo: ./demo/demo.js


With onCommandsChanged prop, app will get an object containing these commandName keys. Values will be one of these strings: inactive, active, disabled, flagged.

Apps can apply formatting / editing commands with ed.execCommand(commandName)

Special case: ed.execCommand('link:toggle', {href, title}) (title optional) to set link of current selection.

Supported commandName keys:




npm start and open http://localhost:8080/

In development mode, webpack builds and serves the targets in memory from /webpack/

Changes will trigger a browser refresh.


Plugins are ES2015 classes with 2 required methods:

  • constructor (ed) {} gets a reference to the main ed, where you can
    • listen to PM events: ed.pm.on('draw', ...)
    • and set up UI: ed.pluginContainer.appendChild(...)
  • teardown () {} where all listeners and UI should be removed


Widgets are mini-editors built to edit specific media types


Run in iframe and communicate via postMessage

Example: ced - widget for code editing


Example: WIP


  1. Primary: Rebass defaults and rebass-theme for global overrides
  2. Secondary: inlined JS style objects (example)
  3. Deprecating: require('./component-name.css') style includes, but needed for some responsive hacks and ProseMirror overrides

code style

Feross standard checked by ESLint with npm test or npm run lint

  • no unneeded semicolons
  • no trailing spaces
  • single quotes

To automatically fix easy stuff like trailing whitespace: npm run lintfix


npm test

Karma is set up to run tests in local Chrome and Firefox.

Tests will also run in mobile platforms via BrowserStack, if you have these environment variables set up:



npm run build

Outputs minified dist/ed.js and copies widgets defined in package.json.


npm version patch - style tweaks, hot bug fixes

npm version minor - adding features, backwards-compatible changes

npm version major - removing features, non-backwards-compatible changes

These shortcuts will run tests, tag, change package version, and push changes and tags to GH.

Travis will then publish new tags to npm and build the demo to publish to gh-pages.