Spell check

The spellcheck module checks spelling from Kotlin through the spell-check engine each operating system already ships. It exposes a Compose wrapper that adds suggestions to a text field's context menu, and an engine API you can call without Compose.

Add the dependency

nucleus-application exposes spellcheck as an api dependency, so the Compose integration is already on the classpath of any Nucleus app:

dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:2.5.0")
}

Add the module explicitly only when you want the engine without the Compose layer:

dependencies {
    implementation("dev.nucleusframework:nucleus.spellcheck:2.5.0")
}

Check a text field

Wrap the field in SpellcheckContextMenu. Right-clicking a misspelled word lists suggestions and an "Add to dictionary" entry above or below the standard Cut/Copy/Paste items:

import androidx.compose.foundation.text.BasicTextField
import dev.nucleusframework.application.spellcheck.SpellcheckContextMenu

@Composable
fun NoteField(value: String, onValueChange: (String) -> Unit) {
    SpellcheckContextMenu(text = value, onTextChange = onValueChange) {
        BasicTextField(value = value, onValueChange = onValueChange, singleLine = true)
    }
}

Picking a suggestion replaces the clicked word and calls onTextChange with the new text.

There is a second overload for the state-based text fields, which manages the text itself:

import androidx.compose.foundation.text.input.rememberTextFieldState
import dev.nucleusframework.application.spellcheck.SpellcheckContextMenu

val state = rememberTextFieldState("helo world")

SpellcheckContextMenu(state = state) {
    TextField(state = state)
}

Choose the check language

Without arguments, the session uses Locale.getDefault(). Pass locale to check one field in a different language:

SpellcheckContextMenu(
    text = value,
    onTextChange = onValueChange,
    locale = Locale.FRENCH,
) {
    BasicTextField(value = value, onValueChange = onValueChange)
}

To switch the whole process, assign SpellChecker.locale. Loading a dictionary touches the disk, so warm the session off the main thread:

import dev.nucleusframework.spellcheck.SpellChecker
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

LaunchedEffect(locale) {
    SpellChecker.locale = locale
    withContext(Dispatchers.IO) { SpellChecker.ensureSession(locale) }
}

Assigning locale drops the current session; the next access builds one for the new language. When you pass both session and locale to the composable, session wins.

Place the menu items

menuPlacement decides whether suggestions land above or below the editing commands:

import dev.nucleusframework.application.spellcheck.SpellcheckMenuPlacement

SpellcheckContextMenu(
    text = value,
    onTextChange = onValueChange,
    menuPlacement = SpellcheckMenuPlacement.Top,
) {
    BasicTextField(value = value, onValueChange = onValueChange)
}

How it works

Each platform has a spell-check engine, reached over JNI. macOS uses NSSpellChecker, Windows uses the Spell Checking API (ISpellChecker), and Linux loads Hunspell with dlopen — so there is no compile-time dependency on a distro package.

A SpellcheckSession owns one loaded dictionary for one locale. SpellChecker keeps a process-wide session and rebuilds it when you change locale. Words you add through "Add to dictionary" are appended to ~/.config/nucleus/spellcheck/<tag>.dic (honoring XDG_CONFIG_HOME); the OS-level learned-word lists on macOS and Windows are left untouched.

When no engine is available — an unsupported platform, a missing Hunspell library, or no matching dictionary — every operation is a no-op instead of an error: check and addToDictionary return false, suggest returns an empty list, and SpellcheckContextMenu renders its content unchanged.

API reference

Compose integration

Package dev.nucleusframework.application.spellcheck, shipped in nucleus-application.

Engine

Package dev.nucleusframework.spellcheck, shipped in spellcheck.

Text helpers

SpellcheckMenuModel.localizedAddToDictionaryLabel(locale) translates the label; the fallback is DEFAULT_ADD_TO_DICTIONARY_LABEL.

Notes

• Tokens are Unicode letters with internal apostrophes. Hyphens split words, and all-digit tokens or tokens longer than 64 characters are skipped.
• SpellChecker.session blocks on first access while the dictionary loads. Use sessionIfReady on a frame path, or warm it with ensureSession() from a background dispatcher.
• Under Jewel, JewelDecoratedWindow and JewelDecoratedDialog install ProvideJewelSpellcheckMenu so the items match Jewel's menu chrome.

What's next

• Context menus — the menu chrome the suggestions appear in.
• Native access — how Nucleus binds to native libraries.
• Ecosystem — JVM libraries that cover the rest of your app.