Customization

You can customize the Grammarly Text Editor Plugin to suit your application's UX. In this guide, we'll cover how to change aspects of the plugin's appearance and behavior using custom CSS variables and EditorConfig properties.

If you're not familiar with the Grammarly experience, we suggest reading the Grammarly UX guide first.

To try out different color, theme, and config options for the plugin, use the Configuratoropen in new window. When you're happy with your configuration, copy the code blocks on the page directly into your project, or click Share to generate a URL that you can share with your friends and teammates.

Theming

Beginning in version 1.8.0, you can theme the plugin by customizing:

• The font family
• The color of interactive elements (buttons and links)
• The border-radiusopen in new window for buttons and cards to create rounded or square corners

Here are three examples of how suggestion cards can be styled (the default is on the left):

Note that theming will also apply to settings menus in the plugin.

Name	Default	Description
--grammarly-default-font-family	Arial, sans-serif	Default font family
--grammarly-interactive-color	#2551DA	Primary color of interactive elements
--grammarly-default-border-radius	4px	Border radius for buttons
--grammarly-card-border-radius	8px	Border radius for suggestion cards

For example, you can theme the plugin as shown in the right-most card in the image above:

grammarly-editor-plugin {
  --grammarly-default-font-family: Optima, sans-serif;
  --grammarly-interactive-color: #e00697;
  --grammarly-default-border-radius: 30px;
  --grammarly-card-border-radius: 0px;
}

Grammarly’s default theme is designed to meet WCAG 2.1open in new window AA color contrast guidelines for font sizes 14px and below. When customizing the colors of your theme, we recommend choosing a color that passes a color contrast ratio of 4.5:1.

Light and dark modes

Beginning in version 1.8.0, the plugin supports both light and dark modes. In light mode, the background is white and the Grammarly button has a black background. In dark mode, the background is dark gray and the Grammarly button has a white background.

You can configure whether the plugin renders in light or dark mode using the color-schemeopen in new window CSS property. color-scheme is an inherited propertyopen in new window, so setting the color-scheme on parent elements will impact how the plugin is rendered.

color-scheme	Description
normal (default)	Render the plugin in light mode
light	Render the plugin in light mode
dark	Render the plugin in dark mode
light dark	Render the plugin in light or dark mode based on the end user’s operating system preference

Here is an example of how to set the plugin to render in light or dark mode based on the end user’s operating system preference:

grammarly-editor-plugin {
  color-scheme: light dark;
}

If you choose to customize the plugin’s interactive color, be mindful of how the color will look against the plugin’s light or dark mode rendering. If you use the light dark color scheme, you may want to set a different interactive color for each scheme. You can set the interactive color based on the user’s preference for light or dark mode using the prefers-color-schemeopen in new window CSS media feature:

@media (prefers-color-scheme: light) {
  grammarly-editor-plugin {
    --grammarly-interactive-color: #e00697;
  }
}

@media (prefers-color-scheme: dark) {
  grammarly-editor-plugin {
    --grammarly-interactive-color: #f7b2e0;
  }
}

Activation

By default, the plugin is activated when a text editor that uses the plugin receives focus. You can set the activation EditorConfig property to immediate to have the plugin initialize as soon as the page loads instead.

Or, 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 disconnect function:

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

Grammarly button

By default, the Grammarly button appears in a fixed position relative to the bottom right of the viewport. If fixed positioning works for your app, but the bottom right isn't ideal, you can customize it using Grammarly’s predefined CSS variables.

Alternatively, you can take complete control and place the Grammarly button on the page.

Fixed position

You can customize the position of the Grammarly button using the following CSS variables:

Name	Default	Description
--grammarly-button-position-bottom	24px	Grammarly button fixed position relative to bottom edge of viewport
--grammarly-button-position-left		Grammarly button fixed position relative to left edge of viewport
--grammarly-button-position-right	24px	Grammarly button fixed position relative to right edge of viewport
--grammarly-button-position-top		Grammarly button fixed position relative to top edge of viewport
--grammarly-button-z-index	1000	Grammarly button z-indexopen in new window

For example, to shift the Grammarly button over to avoid conflicting with an existing button:

grammarly-editor-plugin {
  --grammarly-button-position-right: 100px;
}

Custom position

Another option for positioning the Grammarly button is to use the grammarly-button custom element. The Grammarly button will render wherever that element is found. Note that if you do not include the grammarly-button custom element, the Grammarly button will still be displayed.

The following example positions the Grammarly button in the footer beside the Submit button.

<form class="feedback">
  <grammarly-editor-plugin>
    <textarea></textarea>
  </grammarly-editor-plugin>

  <footer>
    <grammarly-button></grammarly-button>
    <button type="submit">Submit feedback</button>
  </footer>
</form>

The <grammarly-button> element is available as a component in the React and Vue SDK packages.

Note that <grammarly-button> will not inherit any theming or light/dark treatment from <grammarly-editor-plugin>. You will need to set CSS variables on both <grammarly-editor-plugin> and <grammarly-button> or on an element that is a parent to both of them:

grammarly-editor-plugin,
grammarly-button {
  color-scheme: dark;
}

Menu position

You can set the position of the Grammarly button menu relative to the Grammarly button:

Integration	Default	Values	Example
JavaScript	"left"	"left", "right"	<grammarly-button menu-position="right"></grammarly-button>
React	"left"	"left", "right"	<GrammarlyButton menuPosition="right"/>
Vue	"left"	"left", "right"	<GrammarlyButton :menuPosition="right"/>

Tone detector position

You can set the position of the tone detector (if present) relative to the Grammarly button:

Integration	Default	Values	Example
JavaScript	"left"	"left", "right"	<grammarly-button tone-position="right"></grammarly-button>
React	"left"	"left", "right"	<GrammarlyButton tonePosition="right"/>
Vue	"left"	"left", "right"	<GrammarlyButton :tonePosition="right"/>

Underlines

You can decide to programmatically turn underlines off and on, and also change the z-index if needed.

Programmatically turning off underlines

The plugin displays underlines beneath words and phrases that can be improved. Users can turn off underlines from the Grammarly button menu. You can also control whether underlines are on or off programmatically by using the underlines EditorConfig property.

const editor = document.querySelector("grammarly-editor-plugin");
editor.config = {
  underlines: "off",
};

Z-index

You can customize the z-indexopen in new window of suggestion underlines if they are not appearing correctly in your app. This may happen if your app already includes z-index values that the Editor SDK cannot automatically detect.

Name	Default	Description
--grammarly-underline-z-index	auto	Underline z-index

Suggestion cards

You can decide to programmatically turn suggestion cards off and on, and also change the introductory text.

Programmatically turning off suggestion cards

In some cases, you may want to programmatically turn off suggestion cards and then turn them back on. For example, you may want to turn off suggestion cards while a user is interacting with a menu or interactive element in your app and then turn them back on when the user is done.

You can configure whether suggestion cards are displayed by setting the suggestionCards EditorConfig property to on or off:

const editor = document.querySelector("grammarly-editor-plugin");
editor.config = {
  suggestionCards: "off",
};

Introductory text

To provide context for users who are less familiar with Grammarly, suggestion cards include introductory text that appears until users accept or dismiss a suggestion for the first time.

This text can be customized using the introText EditorConfig property to include, for example, your app name:

English dialect

By default, Grammarly sets the English dialect of a user according to their browser's preferred language settingopen in new window, but if you already have a good idea, then it's best to specify it using documentDialect.

Note that the user can always override the dialect via the Grammarly button menu:

Dynamic CSS updates

CSS variables can be accessed and updated using getPropertyValueopen in new window and setPropertyopen in new window:

const element = document.querySelector("grammarly-editor-plugin");
element.style.setProperty("--grammarly-button-position-left", "8px");

console.log(element.style.getPropertyValue("--grammarly-button-position-left"));

If you want to update the CSS variables after the Grammarly Text Editor SDK has already initialized, you may need to dispatch the following event for the UI to update:

document.documentElement.dispatchEvent(
  new Event("grammarly-theme-change", { bubbles: true })
);