Back to reference

GrammarlyEditorPluginElement

<grammarly-editor-plugin> is a web component that adds Grammarly suggestions to the HTML element it wraps.

declare class GrammarlyEditorPluginElement extends HTMLElement {
  addEventListener<K extends keyof GrammarlyEditorPluginElementEventMap>(type: K, listener: (this: HTMLElement, ev: GrammarlyEditorPluginElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions | undefined): void;
  get clientId(): ClientId | undefined;
  get config(): EditorConfig;
  connect(editor: HTMLInputElement | HTMLTextAreaElement | HTMLElement, viewport?: HTMLElement): void;
  disconnect(): void;
  removeEventListener<K extends keyof GrammarlyEditorPluginElementEventMap>(type: K, listener: (this: HTMLElement, ev: GrammarlyEditorPluginElementEventMap[K]) => any, options?: boolean | EventListenerOptions | undefined): void;
}

Properties

clientIdType: ClientId | undefined
configType: EditorConfig

Current editor configuration

Example:

<grammarly-editor-plugin>
  <textarea></textarea>
</grammarly-editor-plugin>
const editor = document.querySelector("grammarly-editor-plugin");
editor.config = { autocomplete: "on", documentDialect: "british" };

Attributes

"client-id"Type: ClientId
"config.documentDialect"Type: DialectDefault: "auto-browser"

Which English dialect should be assumed?

"config.documentDomain"Type: DomainDefault: "general"

What is the style or type of writing?

"config.suggestionCategories.variety"Type: "on" | "off"Default: "on"

Suggests alternatives to words that occur frequently in the same paragraph.

"config.suggestionCategories.vocabulary"Type: "on" | "off"Default: "on"

Suggests alternatives to bland and overused words such as "good" and "nice".

"config.suggestionCategories.fluency"Type: "on" | "off"Default: "on"

Suggests ways to sound more natural and fluent.

"config.suggestionCategories.oxfordComma"Type: "on" | "off"Default: "off"

Suggests adding the Oxford comma after the second-to-last item in a list of things.

"config.suggestionCategories.unnecessaryEllipses"Type: "on" | "off"Default: "off"

Flags unnecessary use of ellipses (...).

"config.suggestionCategories.punctuationWithQuotation"Type: "on" | "off"Default: "on"

Suggests placing punctuation before closing quotation marks.

"config.suggestionCategories.stylisticFragments"Type: "on" | "off"Default: "off"

Suggests completing all incomplete sentences, including stylistic sentence fragments that may be intentional.

"config.suggestionCategories.informalPronounsAcademic"Type: "on" | "off"Default: "off"

Flags use of personal pronouns such as "I" and "you" in academic writing.

"config.suggestionCategories.conjunctionAtStartOfSentence"Type: "on" | "off"Default: "off"

Flags use of conjunctions such as "but" and "and" at the beginning of sentences.

"config.suggestionCategories.prepositionAtTheEndOfSentence"Type: "on" | "off"Default: "off"

Flags use of prepositions such as "with" and "in" at the end of sentences.

"config.suggestionCategories.splitInfinitive"Type: "on" | "off"Default: "on"

Suggests rewriting split infinitives so that an adverb doesn't come between "to" and the verb.

"config.suggestionCategories.missingSpaces"Type: "on" | "off"Default: "on"

Suggests adding missing spacing after a numeral when writing times.

"config.suggestionCategories.passiveVoice"Type: "on" | "off"Default: "off"

Flags use of passive voice.

"config.suggestionCategories.readabilityFillerWords"Type: "on" | "off"Default: "on"

Flags long, complicated sentences that could potentially confuse your reader.

"config.suggestionCategories.readabilityTransforms"Type: "on" | "off"Default: "on"

Suggests splitting long, complicated sentences that could potentially confuse your reader.

"config.suggestionCategories.personFirstLanguage"Type: "on" | "off"Default: "on"

Suggests using person-first language to refer respectfully to an individual with a disability.

"config.suggestionCategories.possiblyBiasedLanguageGenderRelated"Type: "on" | "off"Default: "on"

Suggests alternatives to potentially gender-biased and non-inclusive phrasing.

"config.suggestionCategories.possiblyBiasedLanguageLGBTQIARelated"Type: "on" | "off"Default: "on"

Flags LGBTQIA+-related terms that may be seen as biased, outdated, or disrespectful in some contexts.

"config.suggestionCategories.possiblyPoliticallyIncorrectLanguage"Type: "on" | "off"Default: "on"

Suggests alternatives to language that may be considered politically incorrect.

"config.suggestionCategories.possiblyBiasedLanguageRaceEthnicityRelated"Type: "on" | "off"Default: "on"

Suggests alternatives to potentially biased language related to race and ethnicity.

"config.suggestionCategories.possiblyBiasedLanguageAgeRelated"Type: "on" | "off"Default: "on"

Suggests alternatives to potentially biased language related to older adults.

"config.suggestionCategories.possiblyBiasedLanguageDisabilityRelated"Type: "on" | "off"Default: "on"

Suggests alternatives to potentially ableist language.

"config.suggestionCategories.possiblyBiasedLanguageFamilyRelated"Type: "on" | "off"Default: "on"

Suggests alternatives to potentially biased language related to parenting and family systems.

Quinn hoped to meet their { real father => birth father } one day.

"config.suggestionCategories.numbersZeroThroughTen"Type: "on" | "off"Default: "on"

Suggests spelling out numbers zero through ten.

"config.suggestionCategories.numbersBeginningSentences"Type: "on" | "off"Default: "on"

Suggests spelling out numbers at the beginning of sentences.

"config.suggestionCategories.nounStrings"Type: "on" | "off"Default: "on"

Flags a series of nouns that modify a final noun.

The {store manager policy handbook update meeting } is tomorrow.

"config.suggestionCategories.sentenceVariety"Type: "on" | "off"Default: "on"

Flags series of sentences that follow the same pattern.

I read an interesting book recently. It was about computers. I usually read novels.

"config.suggestionCategories.spacesSurroundingSlash"Type: "on" | "off"Default: "on"

Suggests removing extra spaces surrounding a slash.

I just wanted to send a { reminder / follow-up => reminder/follow-up }.

"config.suggestionCategories.possiblyBiasedLanguageHumanRights"Type: "on" | "off"Default: "on"

Suggests alternatives to language related to human slavery.

My professor wrote a book about { slaves => enslaved people } in America.

"config.suggestionCategories.possiblyBiasedLanguageHumanRightsRelated"Type: "on" | "off"Default: "on"

Suggests alternatives to terms with origins in the institution of slavery.

The apartment’s { master => main|primary } bedroom has a view of the sea.

"config.userFeedback"Type: "on" | "off"Default: "on"

Collect user feedback after the user takes action on 5 suggestions.

We will not request feedback more than once in a 30 day period.

User feedback is required for the Free plan. Learn more about our plans.

"config.introText"Type: stringDefault: "Grammarly helps you write clearly and mistake-free."

Text shown to introduce first-time users to Grammarly.

This introductory text shows in the footer of suggestion cards until the user first accepts or dismisses a suggestion.

"config.toneDetector"Type: "on" | "off"Default: "off"

Show the tone detector interface (beside the Grammarly button).

Note that tone detection requires a text of at least 120 characters and will not activate if the text is over 2500 characters in length.

Tone detector is available only on the Plus plan. Learn more about our plans.

"config.autocomplete"Type: stringDefault: "off"

Offers to complete phrases and emojis for your users as they type. Learn more

Autocomplete is not currently supported for <input> fields.

  • "on": Plugin offers autocomplete and emoji autocomplete suggestions

  • "text": Plugin offers autocomplete suggestions without emoji autocomplete

  • "emoji": Plugin offers emoji autocomplete suggestions without core autocomplete functionality

  • "off": Plugin does not offer autocomplete or emoji autocomplete suggestions

If you have a Content Security Policy (CSP), you will need to update it as described here.

Autocomplete is available only on the Plus plan. Learn more about our plans.

"config.dictionaries"Type: stringDefault: "off"

Use application dictionaries so that Grammarly stops flagging specific words as misspelled. Learn more

For a dictionary to be ready to use, the Dictionary status must be set to On in your App Console.

  • "on": Plugin uses all dictionaries that are ready to use

  • "off": Plugin stops using all dictionaries

  • "dictionary-a": To activate one dictionary, set the alias of one dictionary (where dictionary-a is an example alias)

  • "dictionary-a dictionary-b": To activate two dictionaries, set the aliases of multiple dictionaries

  • "dictionary-a dictionary-b dictionary-{n}": To activate n dictionaries, set the aliases of multiple dictionaries

Application dictionaries are available only on the Plus plan. Learn more about our plans.

"config.oauthRedirectUri"Type: string

URI to redirect to after successful account connection.

"config.oauthAssertionProvider"Type: string | (() => Promise<{ assertion: string; }>)

OAuth assertion to verify ownership of the clientId.

"config.suggestionCards"Type: "on" | "off"Default: "on"

Show suggestion cards when a user hovers over a suggestion underline.

"config.underlines"Type: "on" | "off"Default: "on"

Show underlines for suggestions.

"config.activation"Type: "focus" | "immediate"Default: "focus"

Activation strategy used by the Editor Plugin

  • "focus": Plugin activates once the text field is focused

  • "immediate": Plugin activates immediately

Events

"suggestion-card-open"Type: CustomEvent

Triggered when a suggestion card is opened.

const editor = document.querySelector("grammarly-editor-plugin");
editor.addEventListener("suggestion-card-open", (event) => {
  console.log("Suggestion card shown to user");
});

"suggestion-card-close"Type: CustomEvent

Triggered when a suggestion card is closed.

const editor = document.querySelector("grammarly-editor-plugin");
editor.addEventListener("suggestion-card-close", (event) => {
  console.log("Suggestion card closed");
});

"suggestion-card-action"Type: CustomEvent<{ action: | "accept" | "dismiss" | "close"; }>

Triggered when a suggestion card is acted upon by the user (accept, dismiss, or close).

const editor = document.querySelector("grammarly-editor-plugin");
editor.addEventListener("suggestion-card-action", (event) => {
  console.log("Suggestion card action:", event.detail.action);
});

"plugin-turned-off"Type: CustomEvent

Triggered when the user turns off Grammarly.

const editor = document.querySelector("grammarly-editor-plugin");
editor.addEventListener("plugin-turned-off", (event) => {
  console.log("Grammarly Text Editor SDK turned off");
});

"plugin-error"Type: CustomEvent<Error>

Triggered on fatal error with the plugin.

const editor = document.querySelector("grammarly-editor-plugin");
editor.addEventListener("plugin-error", (event) => {
  console.log("Grammarly Text Editor SDK has thrown an error:", event.detail);
});

"document-stats"Type: CustomEvent<DocumentStats>

Triggered when new text information is available. This event can be used to track features of text as it is being written.

document-stats is available only on the Plus plan. Learn more about our plans.

<div>
  Words: <span data-field="wordsCount"></span> &mdash; Reading time: <span data-field="readingTime"></span> &mdash;
  Speaking time: <span data-field="speakingTime"></span> &mdash; Readability score:
  <span data-field="readabilityScore"></span>
</div>
const editor = document.querySelector("grammarly-editor-plugin");

editor.addEventListener("document-stats", (event) => {
  function update(field, format = (value) => value) {
    document.querySelector(`[data-field=${field}]`).innerText = format(event.detail[field]);
  }
  const formatTime = ({ h, m, s }) => `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;

  update("wordsCount");
  update("readingTime", formatTime);
  update("speakingTime", formatTime);
  update("readabilityScore");
});

"session-stats"Type: CustomEvent<SessionStats>

Triggered when new session information is available. This event can be used to track information about the writing session.

session-stats is available only on the Plus plan. Learn more about our plans.

<ul>
  <li>Duration: <span data-field="duration"></span> seconds</li>
  <li>Suggestions Accepted: <span data-field="suggestionsAccepted"></span></li>
  <li>Suggestions Sent: <span data-field="suggestionsSent"></span></li>
  <li>Words analyzed: <span data-field="wordsAnalyzed"></span></li>
</ul>
const editor = document.querySelector("grammarly-editor-plugin");

editor.addEventListener("session-stats", (event) => {
  function update(field, format = (value) => value) {
    document.querySelector(`[data-field=${field}]`).innerText = format(event.detail[field]);
  }
  const formatBreakdown = ({ total }) => total;

  update("duration");
  update("suggestionsAccepted", formatBreakdown);
  update("suggestionsSent", formatBreakdown);
  update("wordsAnalyzed");
});

Methods

addEventListener()

addEventListener<K extends keyof GrammarlyEditorPluginElementEventMap>(type: K, listener: (this: HTMLElement, ev: GrammarlyEditorPluginElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions | undefined): void;

Parameters

NameTypeDescription
typeK
listener(this: HTMLElement, ev: GrammarlyEditorPluginElementEventMap[K]) => any
optionsboolean | AddEventListenerOptions | undefined

connect()

When inserted into the DOM, the GrammarlyEditorPlugin will automatically detect and connect to an editable child element (editor) and its scrollable container (viewport).

In rare cases, you may need to override what was automatically detected. This function provides a way to do that by specifying a different editor and viewport.

connect(editor: HTMLInputElement | HTMLTextAreaElement | HTMLElement, viewport?: HTMLElement): void;

Examples

See editor-sdk-tinymce-imperativeopen in new window

Parameters

NameTypeDescription
editorHTMLInputElement | HTMLTextAreaElement | HTMLElementthe editable element
viewportHTMLElementscrollable outer element of the editable element

disconnect()

Remove plugin from the editor.

disconnect(): void;

removeEventListener()

removeEventListener<K extends keyof GrammarlyEditorPluginElementEventMap>(type: K, listener: (this: HTMLElement, ev: GrammarlyEditorPluginElementEventMap[K]) => any, options?: boolean | EventListenerOptions | undefined): void;

Parameters

NameTypeDescription
typeK
listener(this: HTMLElement, ev: GrammarlyEditorPluginElementEventMap[K]) => any
optionsboolean | EventListenerOptions | undefined
Last Updated: 5/31/2023, 6:33:38 PM