Skip to main content

Frontend Documentation

The Sapling JavaScript SDK enables grammar correction and autocomplete in any web application.

Sapling.init

Sapling.init({
endpointHostname: 'https://localhost:5000',
editPathname: '/edits',
statusBadge: true,
lang: 'en',
autocomplete: false,
mode: 'prod'
});

init instantiates the SDK.

key - String

Sapling API key. DO NOT set this in JavaScript except for internal development.

endpointHostname - String

Use your own backend hostname like the Python example in Quickstart.

editPathname - String

Use your own backend endpoint pathname like the Python example in Quickstart. Note that this does not have to be a full edits endpoint; you can also use a Sapling spellcheck endpoint to only display spellcheck edits.

statusBadge - Boolean

When set to true, will display a small blue status dot in the bottom right corner of observed text fields. The badge when spin to indicate processing status. We recommend turning this on for a better user experience, except when there are many (10+) text fields on a single page and too many badges might be distracting.

lang - String

Languages other than English are under active development and not enabled on an API key by default. Sapling supports English language variants (US/UK/CA/AU). The setting is available in the dashboard. Refer to this page for the status of other languages, and contact us to enable access.

  • en: english
  • de: german
  • es: spanish
  • fr: french
  • it: italian
  • ja: japanese
  • pt: portugese
  • zh: chinese

variety - String

Only used with English. Specifies regional English spelling options. Defaults to the configuration in the Sapling Dashboard. Supported regions are:

  • us-variety: American English
  • gb-variety: British English
  • au-variety: Australian English
  • ca-variety: Canadian English
  • null-variety: Don’t suggest any changes based on English variety

autocomplete - Boolean

When set to true, will use Sapling's autocomplete language model to suggest sentence autocompletions as a user is typing. This is currently only available to certain API keys upon request. You'll also need to set completePathname.

Sapling.observe

const editable = document.getElementById('editor');
Sapling.observe(editable);

observe takes a single argument, a textarea or contenteditable. The SDK will check text in the dom element in real time and apply edit suggestions.

Mark elements that will be observed by the JavaScript SDK with the attribute sapling-ignore="true" when they are created to prevent duplicate interactions with Sapling browser extensions.

Sapling.unobserve

const editable = document.getElementById('editor');
Sapling.unobserve(editable);

unobserve takes a single argument, a textarea or contenteditable. This will remove edit suggestions and stop any checking on a previously observed element.

Sapling.checkOnce

const editable = document.getElementById('editor');
Sapling.checkOnce(editable);

checkOnce takes a single argument, a textarea or contenteditable.

This function is only recommended for internal use.

Sentences that have not been changed are cached locally and do not count towards bandwidth and API usage more than once. However, SDK users may choose not to trigger text checks in real time for additional bandwidth or API usage savings.

note

Edit markup is applied to the text using DOM Range objects. While they typically update in location with text, depending on changes in text, individual edits may no longer be accurate after the text has been changed, and may result in a confusing user experience.