cmp-form
0.1.0indexedOne-line field+rule DSL for Compose forms with typed FieldState, async server checks, cross-field rules, multi-step wizards, conditional fields, i18n, and optional Material3 bindings.
2
Stars
—
Used by
dependents
—
Health
/ 100
cmp-form
A simple but powerful form validator for Compose Multiplatform. One field + one rule is one line; the full feature set covers async server-side checks, cross-field rules, multi-step wizards, conditional fields, server-error injection, and i18n — without dragging in a heavy framework.
Why this library
Forms in Compose are tedious: a tangle of MutableState, remember, focus-aware blur tracking,
async lookups, and ad-hoc cross-field validation. cmp-form gives you a typed FieldState<T> and
a builder DSL that own the boring parts so your screen code stays the size of a JSX form.
It ships in two artifacts so the validator/state core stays Material3-free for users who bind to a custom design system:
Platform support
Installation
Compose Multiplatform setup
gradle/libs.versions.toml:
[libraries]
cmp-form = { module = "io.github.nadeemiqbal:cmp-form", version = "0.1.0" }
cmp-form-material3 = { module = "io.github.nadeemiqbal:cmp-form-material3", version = "0.1.0" }
commonMain dependencies:
commonMain.dependencies {
implementation(libs.cmp.form) // core: validators + state + DSL
implementation(libs.cmp.form.material3) // optional: drop-in M3 composables
}
Android-only setup
If you're not using Compose Multiplatform — just a regular com.android.application /
com.android.library module with Compose — add the dependencies straight to the Android module:
// app/build.gradle.kts
plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android")
id("org.jetbrains.kotlin.plugin.compose")
}
android {
defaultConfig {
minSdk = 24 // cmp-form requires API 24+
}
buildFeatures { compose = true }
}
dependencies {
implementation("io.github.nadeemiqbal:cmp-form:0.1.0")
implementation("io.github.nadeemiqbal:cmp-form-material3:0.1.0")
// Your existing Compose deps — cmp-form does NOT replace these.
implementation(platform())
implementation()
implementation()
}
That's it — every FormTextField, rememberFormState, validator function in this README works
identically. Gradle resolves the Android variant of the KMP publication automatically; you don't
need to apply the Kotlin Multiplatform plugin or use commonMain.
Requirements / things to verify:
If you only want the headless validator/state core (no Material3 composables), drop
cmp-form-material3 and depend on cmp-form alone — you can then bind FieldState to any
TextField (M2, M3, or your own design system) by wiring field.value, field::onValueChange,
, and manually.
Quick start
val form = rememberFormState {
field("email", "") { validator = required() and email() }
field("password", "") { validator = required() and minLength(8) }
}
FormTextField(field = form.field("email"), label = { Text("Email") })
FormTextField(field = form.field("password"), label = { Text("Password") })
Button(onClick = {
scope.launch {
form.submit { values -> login(values["email"] as String, values[] String) }
}
}) { Text() }
That's a complete, validated login form. required() rejects blanks, email() checks the
format, minLength(8) enforces password length. The DSL hides the MutableState, focus
listeners and "did the user touch the field yet?" bookkeeping.
What's built in
Presence & length — required(), requiredNotBlank(), notNull<T>(), mustBeTrue(),
, , , , , .
Character classes — alphabetic(), numeric(), alphanumeric(), ascii(),
, , , ,
, .
Formats — email(), url(), phone(), , , , ,
, , , (~25 countries bundled).
Numeric — min(), , (any ), , ,
, , (Int/Long), , ,
(String-parseability).
Comparison — equalTo(), notEqualTo(), oneOf(...), notOneOf(...).
Dates (via kotlinx-datetime) — isoDate(), dateInRange(), minAge(), ,
, , , , .
Financial — creditCard() with Luhn + brand restriction, iban() (mod-97), bic() (SWIFT).
Passwords — password { minLength(8); upper(); lower(); digit(); special(); noCommon() }
DSL aggregator, passwordStrength(Strong) for entropy thresholds, scorePassword() for an
unbounded 0..4 strength meter.
Cross-field — matchesField("otherKey"), differentFromField("otherKey"),
whenField("otherKey", predicate, then).
Files — FileSpec value-object + fileSize(), fileExtension(), mimeType() (with
"image/*" wildcard support).
Combinators — a and b (short-circuit), a or b, a andAll b (accumulate every failure),
not(v), whenever(predicate, v), and a contramap(transform) operator for adapting a
validator to a different input type.
Escape hatches — custom("code", "message") { predicate } for sync,
customSuspend("code", "message") { suspendPredicate } for async, plus inline
asyncValidator = ... in the DSL.
Async validation
field("username", "") {
validator = required() and minLength(3) and slug()
asyncValidator = customSuspend("taken", "Username is taken") {
api.usernameAvailable(it)
}
debounce = 400.milliseconds
}
field.isValidating is observable, submit() waits for async checks to resolve before invoking
the handler, and the debounce auto-cancels in-flight requests on new keystrokes.
Trigger modes
Per-field, configurable via triggerMode = ...:
Cross-field rules
field("password", "") { validator = required() and minLength(8) }
field("confirm", "") { validator = required() and matchesField("password") }
Or a form-level rule that runs against the whole snapshot:
formRule("dates") {
if ((get<Int>("start") ?: 0) > (get<Int>("end") ?: 0))
invalid("order", "Start must be ≤ end")
else valid()
}
Multi-step / wizard forms
val form = rememberFormState {
step("account") { field("email", "") { ... } }
step("personal") { field("name", "") { ... } }
}
form.nextStep() // advances only when the current step is valid
enabledWhen { snapshot -> ... } on a field excludes it from validation and from values
when the predicate is false — useful for fields like "Company" that only matter if "Employed"
is checked.
Server errors
try { api.signup(form.values) }
catch (e: HttpException) {
form.setServerErrors(e.fieldErrors) // { "email" to "already registered", ... }
}
i18n / custom messages
object FrenchMessages : FormMessages {
override fun messageFor(code: String, params: Map<String, Any?>) = when (code) {
"required" -> "Champ obligatoire"
"email" -> "Adresse e-mail invalide"
else -> DefaultMessages.messageFor(code, params)
}
}
CompositionLocalProvider(LocalFormMessages provides FrenchMessages) { SignupScreen() }
Each ValidationError also carries a code, so apps using stringResource() can map codes
to platform-native string resources themselves.
State persistence (config changes)
rememberFormState is backed by rememberSaveable with a Saver that round-trips primitive
field values automatically. Reference-typed fields fall back to in-memory (still survive
recomposition, but not Activity recreation).
Sample app
A four-screen sample lives under sample/composeApp/: Login, Signup
(with async username check), Checkout (credit-card + IBAN + postal-by-country) and a
3-step Wizard (with enabledWhen conditional fields).
Run it:
./gradlew :sample:desktopApp:run
./gradlew :sample:webApp:wasmJsBrowserDevelopmentRun
./gradlew :sample:androidApp:installDebug
Roadmap
See out-of-scope in the design doc for the v0.2+ wishlist. Highlights:
Flow<T>API surface for non-Compose consumerscompose-resourcesintegration forFormMessages- Field arrays / repeatable fields (
fieldArray<T>("phones")) - Input masking (format-as-you-type for credit cards / phone)
- Pre-built
cmp-form-testartifact with mock fixtures
Contributing
See CONTRIBUTING.md.
License
Apache 2.0 — see LICENSE.