# Add spelling and grammar proofing

> Connect a spelling or grammar provider to SuperDoc.



Proofing helps people catch spelling and grammar mistakes while they write. SuperDoc underlines the issues; a provider
you choose checks the text and suggests replacements. It does not include a dictionary or grammar checker.

## Try a correction [#try-a-correction]

Expand the Editor and type `teh` followed by a space. Right-click its underline and choose **the**. Type `teh` again
and choose **Ignore** instead: the text stays unchanged, but the issue is dismissed for this editor session.

> **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]

Keep the Editor, sample document, and export button from the [Quickstart](/editor/quickstart). Create
`src/proofing-provider.ts` with this local provider:

```ts
import type { Config } from 'superdoc';

export const proofing = {
  enabled: true,
  provider: {
    id: 'local-example',
    check: async ({ segments, signal }) => {
      signal?.throwIfAborted();
      return {
        issues: segments.flatMap((segment) => {
          return Array.from(
            segment.text.matchAll(/(?<![\p{L}\p{M}\p{N}_])teh(?![\p{L}\p{M}\p{N}_])/gu),
            ({ index }) => ({
              segmentId: segment.id,
              start: index,
              end: index + 3,
              kind: 'spelling' as const,
              replacements: ['the'],
            }),
          );
        }),
      };
    },
  },
} satisfies NonNullable<Config['proofing']>;

```

Import `proofing` into `src/main.ts` in Vanilla or `src/App.tsx` in React:

```ts
import { proofing } from './proofing-provider';
```

Add `proofing` to your existing `new SuperDoc({ ... })` configuration, or pass `proofing={proofing}` to
`SuperDocEditor`. Keep your existing readiness and cleanup handlers.

This provider flags only the lowercase word `teh`, not every spelling mistake. Type `teh teh` and confirm that both
words receive suggestions. It runs locally and needs no service credentials.

## Connect a full checker [#connect-a-full-checker]

Use the [proofing example](https://go.superdoc.dev/examples/proofing) for a local English dictionary. Grammar and style
checking require a provider that detects those issue kinds; enabling proofing alone does not add them.

SuperDoc sends text segments to the provider after edits. Return each issue with its `segmentId` and zero-based UTF-16
offsets into that segment, with an exclusive `end`. Return suggestions in `replacements`; do not edit the document
inside `check()`. Honor the request's `signal` so SuperDoc can cancel stale or timed-out checks.

Report provider failures through `onProofingError`. A failed check does not mean the document has no mistakes.

## Save corrected text [#save-corrected-text]

Choose a replacement, export with the Quickstart's **Export DOCX** button, and reopen the file to check the corrected
word. **Ignore** does not replace text or add a word to a persistent dictionary. Use `ignoredWords` if your application
needs to supply its own saved list of words to skip.

## 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.