FAQ

Which browsers are supported?

The Grammarly Text Editor SDK supports modern versions of all desktop browsers. For example:

  • Chrome
  • Firefox
  • Safari
  • Edge
  • Opera
  • Brave

There is currently no support for Internet Explorer or mobile browsers.

In unsupported browsers, the Grammarly Text Editor Plugin will not activate at all. In other words, the underlying editor will behave normally.

Which rich text editor frameworks are supported?

We regularly test the SDK with the following frameworks for building rich text editors:

  • CKEditor 5
  • Quill 1.3
  • Slate
  • TinyMCE 5 & 6

Which JavaScript libraries and frameworks are supported?

In addition to vanilla JavaScript, we support thin wrappers for React and Vue.

Are Electron applications supported?

Yes, the Text Editor SDK supports Electronopen in new window and similar Chromium-based frameworks.

Are mobile applications supported?

The Text Editor SDK does not support mobile devices at this time.

How does the Grammarly Text Editor Plugin work with the Grammarly Chrome Extension?

If the user has the Grammarly Chrome Extension installed, the extension will override the Grammarly Text Editor Plugin experience.

What kinds of Grammarly communications assistance will users receive in my app?

If your app is on the Free or Starter planopen in new window, users will receive suggestions for correctness.

If your app is on the Plus plan, users will additionally receive suggestions for clarity, engagement, and delivery. On the Plus plan, you can also turn on the tone detector and autocomplete features to provide further assistance to your users.

Note that users who connect their Grammarly Premium or Grammarly Business accounts to your app will always receive suggestions for correctness, clarity, engagement, and delivery, regardless of your app’s plan. However, they won’t have access to tone detector or autocomplete unless your app is on the Plus plan and these features are turned on.

How does the Text Editor Plugin behave when users write in a language other than English?

The plugin ignores non-English text, but it doesn’t turn off. If users later write in English, they’ll receive suggestions for that part of the text. Non-English text is not included in the words checked count for paid plansopen in new window or the Words checked chart in your dashboard.

How is the Text Editor SDK adding UI elements to my text editor? Is it manipulating the DOM?

The SDK doesn’t show suggestions by manipulating your application’s DOM or by adding any styles that might affect your UI. Instead, everything the SDK renders is encapsulated in a web component. Using a custom element and shadow DOMopen in new window, the SDK can draw underlines, highlight text, and show suggestion cards in an overlay that sits on top of the editor. This overlay doesn’t trap, intercept, or prevent any user events from reaching the editor—it’s wholly transparent and invisible to the user.

How do I add Grammarly to my Content Security Policy (CSP)?

If your app includes a Content Security Policyopen in new window, please add the following directives:

img-src data: https://*.grammarly.com;
connect-src https://*.grammarly.com https://*.grammarly.io wss://*.grammarly.com;
style-src 'unsafe-inline';
script-src https://*.grammarly.com;

If you are using a script tag to include the Text Editor SDK, you will also need to add a directive for unpkg.com:

script-src https://*.grammarly.com https://unpkg.com;

Further, if you are using the autocomplete feature, you will need to add a directive for blob: to allow Grammarly to use web workers.

script-src https://*.grammarly.com blob:;

Do you support TypeScript?

Yes. In fact, the source is written in TypeScript and each package is published along with its types. This allows you to be certain your integration is correct and provides an easy way to discover configuration.

What are the best practices for integrating the SDK with an app that uses multiple environments (e.g., dev/qa/prod)?

We recommend creating a separate Grammarly for Developers app for each environment. Each app can have up to two trusted authentication keys per app, and if you decide to turn on trusted authentication, it’s a best practice for each environment to have its own key.

Is there a way to activate the plugin immediately, before a user selects the text editor?

Yes! Beginning in v2.0.0, you can use the activation EditorConfig property. If you set activation to immediate, the plugin will initialize when the page loads rather than waiting for the text editor to receive focus.

How do I turn the plugin on and off conditionally?

You can use the following code to initialize the plugin only when you’re ready to show it:

Grammarly.init().then((grammarly) => {
  grammarly.addPlugin(
    document.querySelector("textarea"), // or input, [contenteditable]
  );
});

You can turn the plugin off at any time using the following code:

document.querySelector("grammarly-editor-plugin").disconnect();

If you’re running into a situation where your UX conflicts with Grammarly’s underlines or suggestion cards (e.g., you have your own underlines or popups that appear near text), you can temporarily turn the underlines or cards off. To do so, use the underlines or suggestionCards EditorConfig properties.

If I add the Text Editor Plugin to an editor, can I exclude certain HTML elements in the editor from review?

Yes, you can. As of version 1.3.2, the plugin will ignore HTML elements that have the attribute data-grammarly-skip. This content won’t be sent to Grammarly servers and won’t be checked.

Here’s an example:

<grammarly-editor-plugin>
  <div contenteditable>
    <p>This is text that should be checked.</p>
    <quote data-grammarly-skip>
      <p>
        This is a quote, so its original phrasing should be retained, even if there are grammar mistakes or words are
        spelt (sic) wrong.
      </p>
    </quote>
  </div>
</grammarly-editor-plugin>

I use div or span HTML elements rather than semantic elements in my editor DOM, and Grammarly suggestions are behaving strangely. What’s going on and how do I fix this?

To deliver writing suggestions, the Text Editor SDK uses the DOM to develop a semantic representation of the text in the editor. The SDK looks for elements like b, em, and li to understand the text contents and formatting. It also uses the presence of a block-level elementopen in new window to detect where there’s a sentence break in the content.

Using non-semantic elements like div or span rather than semantic elements like p or b can cause Grammarly suggestions to behave in unexpected ways. Here’s an example:

<div class="custom-text">
  This DOM structure might cause an
  <div class="custom-italics-text">un</div>
  intentional issue.
</div>

When interpreting this text, the SDK assumes that there is a line break before and after the custom-italics-text div, since div is a block-level element. Grammarly’s internal representation of the text would look something like this:

This DOM structure might cause an<br />un<br />intentional issue.

Since the intended semantic meaning wasn’t preserved, Grammarly’s suggestions might not work as expected.

The solution is to use the custom data-grammarly-is attribute, available in version 1.6.8 and above, to tell Grammarly what an element represents semantically:

<div class="custom-text" data-grammarly-is="p">
  By telling Grammarly what an element represents semantically, we’ve avoided an
  <div class="custom-italics-text" data-grammarly-is="em">un</div>
  intentional issue.
</div>

What happens if the SDK throws an error?

The plugin is designed to fail gracefully. Suggestion cards and underlines will hide. The plugin will report the error to Grammarly, and you can also be notified by adding an event listener for the plugin-error event.

How do I debug issues with the SDK?

Here are the steps that we recommend:

  • Upgrade to the latest version of the SDK and check if the error still occurs.
  • Check the console in your browser's developer toolsopen in new window for warnings and error messages. As of version 1.7.5 and above, some error codes may direct you to the Error Explainer page to view the complete message.
  • Check the Network tab in your browser's developer tools and filter by “grammarly” to see if any requests are being blocked.
  • Run Grammarly.debug() from the console and look for potential problems.
  • Run Grammarly.printLogs(true) from the console and look for potential problems.

If you're still having problems, let us knowopen in new window and we'll investigate.

Does the Text Editor SDK support users in all countries and regions?

Consistent with applicable trade laws, Grammarly (like other similar organizations) doesn't support some of our services in certain countries or regions. As such, users of your apps may not be able to use the Grammarly SDK services from these restricted geographies.

How will Grammarly blocking access to its services in Russia and Belarus affect my users?

Grammarly made the decision to suspend service in Russia and Belarus after Russia launched an unprovoked invasion of Ukraine in February 2022, which included attacks across the Belarusian border. Grammarly stands with Ukraineopen in new window, and consequently, users with IP addresses originating in Russia and Belarus are not able to access Grammarly functionality. Read below to understand how the Text Editor SDK will behave for users in those regions.

End users of applications with IP addresses in Russia and Belarus, who are using applications with SDK versions 1.5.0+ (including newer major, minor, and patch releases) as well as patch releases of 1.2, will experience the following:

  • The Grammarly Text Editor Plugin will not show any suggestions
  • The Grammarly button will display the Grammarly logo with the colors of the Ukraine flag
  • Hovering over the Grammarly button will show a tooltip explaining that Grammarly has suspended access
  • Clicking the Grammarly button will open a card indicating that Grammarly service is unavailable in their country
Screenshot of what users with new versions of the SDK will see if they have IP addresses from Russia or Belarus

Users who have IP addresses in Russia or Belarus and who are using an application that has integrated any version of the SDK older than the ones listed above will experience the following:

  • The Grammarly Text Editor Plugin will not show any suggestions
  • The Grammarly button will display a red dot on top of the Grammarly logo
  • Hovering over the Grammarly button will show a tooltip indicating Grammarly service is not available
Screenshot of what users with older versions of the SDK will see if they have IP addresses from Russia or Belarus
Last Updated: 9/28/2022, 10:37:47 PM