Migrating from 1.x to 2.x

Migrating to 2.x is recommended, as all new feature development will occur on that track. Only critical bugfixes will be ported back to the 1.x series.

There are some breaking changes between version 1.11.x and 2.0, but all APIs that are removed in version 2.0 are deprecated in version 1.11. If your app's test suite runs using version 1.11 without deprecation warnings, you should be safe to upgrade to version 2.


The following options on the EditorConfig interface have been changed.

  • collectUserFeedback is now userFeedback.
  • showToneDetector is now toneDetector.
  • suggestions is now suggestionCategories.
  • The oauth option is now specified at the top level as oauthRedirectUri.
  • The ui options are now specified at the top level as introText and toneDetector.
  • The document options are now specified at the top level as documentDomain and documentDialect.
  • The onPluginDisable callback has been removed. Use the plugin-turned-off event instead.
  • The onPluginError callback has been removed. Use the plugin-error event instead.
  • The onTextStats callback has been removed. Use the document-stats and session-stats events instead.

All options that previously accepted true/false (suggestions, showToneDetector, collectUserFeedback, etc.) now accept "on"/"off" instead. The strings "on"/"off" are easier to specify as an HTML attribute, and more consistent with our other options.

Top-level APIs

  • The imperative API withElement has been renamed to addPlugin. It accepts the same arguments, but the return value is a GrammarlyEditorPluginElement DOM node instead of an Editor instance.
  • withQuerySelector has been removed. Use document.querySelectorAll(selector).forEach(el => Grammarly.addPlugin(el, config)) instead. This was an infrequently used function and it has been removed to reduce our API surface area.
  • The EditorFactory name is no longer available. It was an alias for EditorSDK.


The Vue 3 package is now the default export. If you're using Vue 2, you'll need to update your import paths from @grammarly/editor-sdk-vue to @grammarly/editor-sdk-vue/v2.

Imports from @grammarly/editor-sdk-vue/v3 will continue to work, but can also be changed to @grammarly/editor-sdk-vue.


An extra <div> wrapper in the <Grammarly> component has been removed. This was causing problems with server rendering and hydration for some users.


  • Version 2 of the Editor SDK will throw an error when using a feature that is unavailable in the current subscription planopen in new window.
  • Some deprecated suggestion categories have been removed:
    • For example, PossiblyOutdatedLanguageLgbtRelated is now PossiblyBiasedLanguageLgbtqiaRelated.
Last Updated: 3/14/2023, 9:49:03 PM