# User dictionary

A **user dictionary** is a personal dictionary that allows end users to store custom words such as acronyms, proper names, and complex terms. Words added to a user dictionary are treated as correct during spellcheck. With the algorithmic spelling engine, these words also appear in the suggestions list. With AI-based spelling, they won't be flagged as incorrect but won't appear as suggestions.

User dictionaries are **language-agnostic**. Words in different languages are all stored in one dictionary regardless of the spell-check language selected.

End users manage their dictionaries through the product UI (WProofreader or SCAYT). There's no admin panel interface for user dictionaries. For instructions on creating dictionaries, adding words, and managing the wordlist from the product UI, refer to the [WProofreader user manual](/user-manuals/user-manual.md).

API command name: `user_dictionary` ([API reference](/api-reference/overview.md))

### How it works

By default, when a user adds words without creating a named dictionary, those words are stored only in the **browser local storage**. This means the words are limited to that specific browser and device and will be lost if the storage is cleared.

Once a user creates a named dictionary, all words, including any previously stored in local storage, are moved to the server. This allows the user to access the dictionary from different browsers, machines, and devices.

The dictionary is available only to the user who created it and knows the dictionary name, or to users for whom the dictionary was programmatically predefined by an admin via the `userDictionaryName` configuration parameter.

### Predefined user dictionary

Admins can pre-assign a named dictionary for users by setting the `userDictionaryName` option in the WProofreader configuration. This ensures that words are always stored server-side from the start, with no reliance on browser local storage.

If you set the same `userDictionaryName` value for multiple users, they'll all share the same dictionary. Words added by any of those users will be visible to all of them. To keep dictionaries personal, assign a unique dictionary name per user, for example based on user ID or username.

#### Configuration by integration

| Integration                                    | Parameter                                             |
| ---------------------------------------------- | ----------------------------------------------------- |
| WProofreader SDK (including CKEditor 5 plugin) | `userDictionaryName: 'dictionary-name'`               |
| SCAYT plugin for CKEditor 4                    | `config.scayt_userDictionaryName = 'dictionary-name'` |

#### Example: WProofreader configuration with a predefined user dictionary

```html
<script>
window.WEBSPELLCHECKER_CONFIG = {
    ...
    userDictionaryName: 'user-123-dictionary'
};
</script>
```

#### Hiding dictionary preferences from end users

You can prevent end users from removing, renaming, or disconnecting the predefined dictionary by adding the `disableDictionariesPreferences` option. When enabled, the dictionary settings section in the product UI will be hidden.

```html
<script>
window.WEBSPELLCHECKER_CONFIG = {
    ...
    userDictionaryName: 'user-123-dictionary',
    disableDictionariesPreferences: true
};
</script>
```

#### Example: SCAYT plugin for CKEditor 4

```javascript
config.scayt_userDictionaryName = 'user-123-dictionary';
```

### Limitations

| Limit                     | Value                                                |
| ------------------------- | ---------------------------------------------------- |
| Max dictionary size       | 50 KB (approximately 10,000 words)                   |
| Max dictionaries per user | Unlimited, but only one can be active at a time      |
| Max characters per word   | 63                                                   |
| Dictionary naming         | Latin characters and/or digits only. Must be unique. |

Words can't contain spaces, dots at the beginning or end, punctuation, or special characters. Duplicate words are rejected automatically. Words can't be edited. To modify a word, delete it and add the corrected version.

### Self-hosted management

For file locations, Docker paths, persistence notes, and direct server-side management, see [User dictionary: self-hosted management →](/features/custom-dictionary/user-dictionary-self-hosted-management.md).

### API reference

The `user_dictionary` API allows programmatic management of user dictionaries, including creating and deleting dictionaries, adding and removing words, and retrieving wordlists.

[User dictionary API reference](/api-reference/user-custom-dictionary-api.md)

### FAQ

#### Are words in the user dictionary case-sensitive?

Yes. The system compares the exact string stored in the dictionary with the word entered in the text field. However, a lowercase word will also be accepted when written with an initial capital letter. For example, adding "*webspell*" means both "*webspell*" and "*Webspell*" are treated as correct, but "*WEBSPELL*" isn't. A word added with an initial capital will only match that exact casing.

#### Are user dictionary words language-specific?

No. User dictionaries are language-agnostic. Words are stored in a single dictionary regardless of which spell-check language is selected.

#### Can a user have more than one dictionary?

Yes, users can create multiple dictionaries. However, only one dictionary can be connected and active at a time. To switch dictionaries, the user must disconnect the current one and connect another.

#### Where are dictionary words stored?

By default, words are stored in the browser local storage. Once a user creates a named dictionary, all words, including those from local storage, are moved to the server. For Cloud deployments, dictionaries are stored on WebSpellChecker servers and associated with a Service ID. For self-hosted deployments, dictionaries are stored as server-side files. For file paths and admin access details, see [User dictionary: self-hosted management →](/features/custom-dictionary/user-dictionary-self-hosted-management.md).

#### Is it possible to protect a user dictionary with a password?

No. This functionality isn't available. The recommended approach is to use a complex, unique name for the dictionary.

#### What happens if I clear my browser storage and don't have a named dictionary?

All words are lost. Creating a named dictionary or having an admin predefine one via `userDictionaryName` ensures words are saved server-side and aren't affected by browser storage changes.

For end-user instructions on creating, connecting, renaming, and deleting dictionaries via the product UI, refer to the [WProofreader user manual →](/user-manuals/user-manual.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wproofreader.com/features/custom-dictionary/user-dictionary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.