# Add spelling and grammar proofing

> Connect a spelling or grammar provider to SuperDoc.



Proofing helps people catch spelling and grammar mistakes while they write, before those mistakes reach a reader. Word processors usually underline an issue so the writer can replace or ignore it without leaving the document.

> **Interactive editor: Try proofing**
>
> Preset: `proofing`.
>
> Proofing: type `mispelled`, `workng`, or `teh`, then right-click the underline.
>
> Local DOCX selection: disabled.


## Enable proofing [#enable-proofing]

SuperDoc schedules checks, underlines issues, and handles Ignore and replacements. It does not include a dictionary or grammar checker, so you provide one:

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/contract.docx',
  proofing: {
    enabled: true,
    provider: {
      id: 'local-example',
      check: async ({ segments }) => ({
        issues: segments.flatMap((segment) => {
          const start = segment.text.indexOf('teh');
          return start < 0
            ? []
            : [{ segmentId: segment.id, start, end: start + 3, kind: 'spelling', replacements: ['the'] }];
        }),
      }),
    },
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

This provider flags only `teh`. For a complete local dictionary, see the [proofing example](https://go.superdoc.dev/examples/proofing).

SuperDoc sends text segments to the provider after edits. Return spelling, grammar, or style issues with zero-based UTF-16 offsets. Honor the request's `signal` so SuperDoc can cancel stale or timed-out checks.

## Configure proofing [#configure-proofing]

Start with **Setup**, then open the other groups only when you need them. Proofing runs only when both `enabled: true` and `provider` are present.

### Setup

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `enabled` | `boolean` | `false` | Optional | Enables proofing. A provider is also required before SuperDoc runs checks. | Enables proofing. A provider is also required before SuperDoc runs checks. | — |
| `provider` | `{ id: string; getCapabilities?: () => ProofingCapabilities \| Promise<ProofingCapabilities>; check: (request: ProofingCheckRequest) => Promise<ProofingCheckResult>; dispose?: () => void \| Promise<void>; } \| null` | `null` | Optional | Checks the text segments SuperDoc supplies and returns spelling, grammar, or style issues. | Checks the text segments SuperDoc supplies and returns spelling, grammar, or style issues. | — |

### Behavior

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `defaultLanguage` | `string \| null` | `null` | Optional | Fallback language passed to the provider when a text segment has no resolved language. | Fallback language passed to the provider when a text segment has no resolved language. | — |
| `debounceMs` | `number` | `500` | Optional | Delay in milliseconds between an edit and the next proofing check. Values at or below 0 run without a delay. | Delay in milliseconds between an edit and the next proofing check. Values at or below 0 run without a delay. | — |
| `maxSuggestions` | `number` | — | Optional | Suggestion limit passed to the provider. The provider decides how to apply it. | Suggestion limit passed to the provider. The provider decides how to apply it. | — |
| `allowIgnoreWord` | `boolean` | `true` | Optional | Shows Ignore in the proofing context menu. Ignored words remain suppressed for this editor session. | Shows Ignore in the proofing context menu. Ignored words remain suppressed for this editor session. | — |
| `ignoredWords` | `string[]` | `[]` | Optional | Words whose proofing issues SuperDoc suppresses. Matching is case-insensitive after Unicode normalization. | Words whose proofing issues SuperDoc suppresses. Matching is case-insensitive after Unicode normalization. | — |
| `timeoutMs` | `number` | `10000` | Optional | Maximum provider call time in milliseconds. Non-positive or non-finite values use the default. | Maximum provider call time in milliseconds. Non-positive or non-finite values use the default. | — |

### Events

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `onProofingError` | `(error: { kind: "provider-error" \| "validation-error" \| "timeout"; message: string; segmentIds?: string[]; cause?: unknown; }) => void` | — | Optional | Runs when a provider check fails or times out. | Runs when a provider check fails or times out. | — |
| `onStatusChange` | `(status: ProofingStatus) => void` | — | Optional | Runs when the proofing lifecycle status changes. | Runs when the proofing lifecycle status changes. | — |

### Reserved

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `visibleFirst` | `boolean` | — | Optional | Prioritize checking visible pages first. | Prioritize checking visible pages first. | — |
| `maxConcurrentRequests` | `number` | — | Optional | Maximum concurrent provider requests. | Maximum concurrent provider requests. | — |
| `maxSegmentsPerBatch` | `number` | — | Optional | Maximum segments per provider call. | Maximum segments per provider call. | — |


Options under **Reserved** are present in the TypeScript type but do not affect the current runtime.

## Protect document text [#protect-document-text]

If the provider uses a network, document text leaves the browser. Obtain user consent, send only the required segments over authenticated encrypted transport, define how the service retains and deletes the text, and never include document text in URLs or logs.