kformik

1.10.0indexed

Formik-style form-state engine with suspendable field operations, schema DSL and sync/async validation, nested/array fields, introspection, array helpers, and annotation-driven typed value code generation.

AndroidJVMNative·Apdelrahman1911/kformik

Stars

—

Used by

dependents

Health

/ 100

Kformik

Kotlin Multiplatform port of Formik. Same form-state engine, written in Kotlin, with no opinion about your UI layer. Drop it into a coroutine, a Jetpack Compose screen, or a SwiftUI view and read state from a StateFlow.

Install

The plugins you'll need depend on what you're building. Apply only what's relevant — core users don't need anything beyond the Kotlin plugin.

Targets: JVM 17+, Android (minSdk 21 for core / 24 for the Compose adapter), iOS (iosX64, iosArm64, iosSimulatorArm64).

The kformik-compose adapter is a Compose Multiplatform module — works in shared commonMain code on Android, Desktop JVM, and iOS. See the Compose section below.

What's in it

Plain Map<String, Any?> forms or typed data class forms (via a ValuesUpdater, hand-rolled or KSP-generated).

Three validation flavors, mix and match:

a synchronous validate: (V) -> FormikErrors callback
an async one (suspend (V) -> FormikErrors)
a schema DSL

Same form, two ways

The schema is a regular Kotlin DSL — formSchema<V> { … } is a normal function with a lambda receiver, like buildString { } or apply { }. Inside it, field("name") { … } opens a builder for one path's rules. No code generation or compiler magic — every block is just a method call with a trailing lambda.

Built-in rules

required, minLength, maxLength, email, pattern (regex), min, max (numeric), and for anything else. Full reference: .

Cross-field rules

Use custom. The rule lambda takes two arguments — the value at the field being declared (v) and the whole form snapshot (all) — and returns a nullable error message (return null to pass, a non-null String to fail):

val schema = formSchema<Map<String, Any?>> {
    field("password") {
        required()
        minLength(8)
    }
    field("confirm") {
        required()
        // `v` is the current value at "confirm"; `all` is the whole form snapshot, so you can
        // compare to any other path. Return null to pass, a message to fail.
        custom("Doesn't match") { v, all -> if (v == all["password"]) null else "Doesn't match" }
    }
}

Nested fields and array indices

Field paths in the schema accept the same dot / bracket syntax as setFieldValue:

val schema = formSchema<Map<String, Any?>> {
    field("user.email")          { required(); email() }
    field("user.address.city")   { required() }
    field("tags[0]")             { minLength(3) }
}

When to use which

You can also combine them — set a schemaValidator AND a validate callback on the same FormikConfig; both run and their errors merge.

Multi-error collection

By default the schema stops at the first failing rule per field. Pass failFast = false to collect every failure:

val schema = formSchema<Map<String, Any?>>(failFast = false) {
    field("password") {
        required()
        minLength(8)
        custom("Must contain a digit") { v, _ -> if (v.toString().any(Char::isDigit)) null else "Must contain a digit" }
    }
}
// validateAllField suspends — call it from a coroutine or suspend function:
val errors = schema.validateAllField(values, "password")
// ["Required", "Too short", "Must contain a digit"]

Introspection

The schema is data — you can ask it questions without running validation:

schema.isRequired("email")        // true
schema.requiredFields()           // {"email", "password", "confirm"}
schema.fieldInfo("password")      // FormFieldInfo(path, rules, isRequired)

Nested paths and array paths work everywhere a path string does:

form.setFieldValue("user.address.city", "Lagos")
form.setFieldValue("tags[1]", "gamma")
form.setFieldError("friends[0].name", "Required")

Field arrays handle structural mutations and keep touched / errors aligned with the rows:

val friends = form.array("friends")
friends.push("aisha")             // append, doesn't touch
friends.insert(1, "between")
friends.swap(0, 2)
friends.move(2, 0)
friends.remove(0)
friends.pop()
friends.replace(0, "REPLACED")    // doesn't touch

The rest of Formik's surface is here too: validateOnChange / validateOnBlur / validateOnMount, dirty, isValid, submitCount, setStatus, submit-touches-all, async submit (suspending), per-field error overrides, and .

Debounced + async validation (v1.7.0+)

Two FormikConfig knobs let you sidestep "validate fires on every keystroke" for expensive checks:

val form = FormikController(FormikConfig(
    initialValues = mapOf("username" to ""),
    validate = { v -> buildErrors {                       // cheap sync — runs every change
        if ((v["username"] as String).isBlank()) put(, )
    }},
    validateAsync = { v -> buildErrors {                  
         (api.isUsernameTaken(v[]  String)) put(, )
    }},
    validateDebounceMs = ,                            
    onSubmit = {  },
))

validateAsync is sync-then-async circuit-broken: a failure in the cheap sync layer skips the async pass entirely, so an empty username doesn't hit the network. Debounce only applies to change-triggered validation — blur, submit, and explicit validateForm() always run immediately.

Hydration: server-side errors / pre-touched fields

Constructor params on both FormikConfig and rememberFormik let you seed initial state — useful when re-rendering a form with server-returned errors after a failed submit:

val form = rememberFormik(
    initialValues = serverPayload.values,
    initialErrors = serverPayload.errors,        // FormikErrors(mapOf("email" to "Already taken"))
    initialTouched = serverPayload.touched,      // FormikTouched(mapOf("email" to true))
    initialStatus = serverPayload.banner,
    onSubmit = { /* … */ },
)

Backend-driven rules (v1.10.0+)

When your backend ships validation metadata (age requires min: 18, max: 60; username adds a server-side serverUniqueCheck), you typically don't want to hardcode each constraint at the call site. A RuleRegistry maps named rules to handlers and lets you apply rule descriptors () inside any existing or block — composing on top of the same DSL, no separate code path.

Field and KformikForm public APIs are unchanged in v1.10.0. The registry composes via the existing rules lambda — Field(rules = { specs(registry, specsFromBackend) }) — so no data-class ABI churn, no @Composable signature break, no migration. Existing forms keep working untouched.

Built-in rules. Calling ruleRegistry() (or ruleRegistry { … }) seeds the seven declarative built-ins from the schema DSL:

custom and customValue are intentionally not registry citizens — a backend-resolvable custom would have to carry a Kotlin function in its params, which violates the "params are plain data" contract. Use register(name, handler) to attach project-specific rules by name (next snippet).

Applying a backend payload to a field:

val registry = ruleRegistry<Map<String, Any?>>()        // 7 built-ins, no extensions

// Parsed from your wire format (kotlinx-serialization JsonObject, Moshi, …) at the boundary.
// RuleSpec is intentionally NOT @Serializable — the library does not ship a JSON layer.
val ageSpecs = listOf(
    RuleSpec("min", mapOf("value" to ,  to )),
    RuleSpec(, mapOf( to )),
)

KformikForm(
    fields = mapOf(
         to Field(FieldType.Number(asInt = ), label = ,
                       rules = { specs(registry, ageSpecs) }),
    ),
    onSubmit = { values ->  },
)

Registering a custom named rule (sync or async):

val registry = ruleRegistry<Map<String, Any?>> {
    register("serverUniqueCheck") { params ->
        val msg = params.stringOrNull("message") ?: "Already taken"
        custom() { value, _ ->
             s = value ? String ?:  
             (s.isBlank())  
            
            
             (userApi.isTaken(s)) msg  
        }
    }
}

Aliases for backend/client name mismatches:

val registry = ruleRegistry<Map<String, Any?>> {
    alias(from = "length_min", to = "minLength")    // backend ships snake_case
    alias(from = "length_max", to = "maxLength")
}
// A spec with name "length_min" now resolves to the canonical minLength handler.
// FieldRule.name in the resulting schema is the CANONICAL "minLength", so
// schema.fieldInfo / isRequired / requiredFields stay deterministic regardless of which
// alias the consumer used at the call site.

Re-declaring the same alias from overwrites the previous mapping (last-write-wins, mirroring register). Cycles (a → b; b → a) and chains longer than 8 alias edges are caught at build() time with RuleResolutionException.

Unknown-rule policy + observability for prod rollouts:

val registry = ruleRegistry<Map<String, Any?>> {
    unknownRulePolicy(UnknownRulePolicy.Skip)               // don't throw; drop the spec
    onUnknownRule { spec -> Logger.warn("Skipped: ${spec.name}") }  // fire once per skip
    register("serverUniqueCheck") { params -> /* … */ }
}

The default policy is UnknownRulePolicy.Throw — a misconfigured / stale-client spec crashes the form loudly during composition, before any user sees broken validation. Skip is opt-in for cases where the backend may ship new rule names ahead of the client; wire onUnknownRule alongside it (silent Skip is debugging-hostile). The callback fires once per skipped RuleSpec resolution; if your callback itself throws, that exception propagates out (no defensive try/catch around it).

Param coercion. RuleParams is the typed view over RuleSpec.params: Map<String, Any?>. Numeric accessors (int, long, , ) accept any and narrow exact-only — important because kotlinx-serialization decodes JSON integers as and decimals as . The exact-only narrowing means:

Schema-build-time vs validate-time errors. Both RuleResolutionException (unknown rule with Throw policy, alias cycle, alias chain too deep) and (missing required param, type mismatch) are thrown at — when runs during composition. They are routed through , because misconfigured specs are programming errors that should crash loudly in dev/staging. Errors from the validation phase (e.g. a registered rule's lambda throwing while validating) DO route through , exactly like hand-written DSL rules.

Mixing specs and inline DSL on the same field — the rules lambda is just Kotlin, source-ordered:

Field(FieldType.Email, required = true, rules = {
    specs(registry, backendSpecs)                   // backend baseline first
    custom("notDisposable") { v, _ ->               // local polish appended after
        val s = v as? String ?: return@custom null
        if (s.endsWith("@disposable.example")) "No disposable emails" else null
    }
})

Field.required = true still auto-injects a required() rule once — including the case where a backend spec also says {"name": "required"} (the existing two-pass dedupe inspects rule names regardless of source, so spec-required and DSL-required collapse to one).

The included BackendDrivenRulesScreen in :sample-forms-cmp-app demonstrates the whole flow end to end against a simulated delay(300) fetch — a custom serverUniqueCheck rule, a length_min → minLength alias, and a backend payload driving three fields.

Typed values with KSP

Annotate a data class:

@FormValues
data class LoginValues(val email: String, val password: String)

The processor generates two siblings:

object LoginValuesPaths {
    const val email    = "email"
    const val password = "password"
}

object LoginValuesUpdater : ValuesUpdater<LoginValues> { /* generated get/set/leafPaths */ }

Which means no stringly-typed paths and no hand-rolled when (path) { … } boilerplate:

val form = FormikController(FormikConfig(
    initialValues = LoginValues("", ""),
    valuesUpdater = LoginValuesUpdater,
    onSubmit = { v, _ -> api.login(v.email, v.password) },
))

form.setFieldValue(LoginValuesPaths.email, "user@example.com")
form.setFieldError(LoginValuesPaths.password, "Too short")

Nested @FormValues data classes nest the path scope (UserValuesPaths.address.city). Lists, maps, sealed types, and generics aren't generated yet; for those, fall back to string paths and either hand-roll the ValuesUpdater or stay with Map<String, Any?>. Full walkthrough in docs/KSP_TYPED_PATHS.md.

Generating typed paths on demand

KSP runs automatically whenever the Kotlin compiler runs — e.g. ./gradlew build, an Android Studio "Build → Make Project", or any save when Build project automatically is enabled in IntelliJ. The Paths / Updater files appear in build/generated/ksp/.../kotlin/, which the IDE already indexes as a source root.

If you'd rather have a single named task that regenerates the @FormValues outputs without running a full project build, paste this snippet into your build.gradle.kts:

tasks.register("generateKFormikTypedPaths") {
    group = "kformik"
    description = "Run KSP to generate @FormValues typed paths and ValuesUpdater objects (no full build)."

    // tasks.matching is lazy and project-shape-agnostic — picks up whatever KSP tasks the active
    // Kotlin / Android / KMP configuration registered: kspKotlin (JVM), kspDebugKotlin (Android),
    // kspCommonMainKotlinMetadata + kspKotlinJvm/IosX64/… (KMP).
    dependsOn(tasks.matching { it.name.startsWith("ksp") && it.name.contains("Kotlin") })
}

The task shows up in IntelliJ / Android Studio's Gradle tool window under a kformik group. Run it from the IDE or ./gradlew generateKFormikTypedPaths to refresh only the generated outputs, skipping the rest of the build.

Compose

kformik-compose is a Compose Multiplatform module. The same rememberFormik(…) API works in shared commonMain code on:

Use it from any of those, including from commonMain:

// shared commonMain code:
@Composable
  {
     form = rememberFormik(
        initialValues = mapOf<String, Any?>( to ,  to ),
        validate = { v -> buildErrors {  } },
        onSubmit = { v, _ ->  },
    )
     state  form.state

    OutlinedTextField(
        value = state.values[]  String,
        onValueChange = { form.setFieldValue(, it) },
        isError = form.displayError() != ,
        supportingText = { form.displayError()?.let { Text(it) } },
    )
    Button(onClick = { form.submit() }, enabled = !state.isSubmitting) {
        Text()
    }
}

The form-state code above compiles unchanged on Android, Desktop, and iOS. The only platform-specific layer is the choice of OutlinedTextField / Button widgets (Material 3 on Android + Desktop; Compose Multiplatform Material on iOS).

Field-grained recomposition

The example above subscribes to whole-form state via form.state — fine for small forms, but every keystroke in any field recomposes every reader. For non-trivial forms, prefer fieldState(name): a per-field State<FieldBinding<Any?>> backed by a deduplicated flow that only emits when that field's value / error / touched changes.

@Composable
fun EmailRow(form: ComposeFormik<Map<String, Any?>>) {
    val email by form.fieldState("email")    // recomposes ONLY on email changes
    OutlinedTextField(
        value = (email.value as? String).orEmpty(),
        onValueChange = { form.setFieldValue("email", it) },
        isError = email.displayError != null,
        supportingText = { email.displayError?.let { Text(it) } },
    )
}

For typed forms, valueOf<T>(name) and fieldOfOrNull<T>(name) give you a typed read without the as? String ceremony.

Fire-and-forget submit + `onError`

ComposeFormik.submit() / resetForm() are deliberately non-suspending so they can be wired into onClick = { form.submit() } without ceremony. Under the hood they call controller.handleSubmit() / handleReset(), which launch on the controller's scope. Anything onSubmit throws on that path is silently swallowed unless you opt into an sink:

val form = rememberFormik(
    initialValues = mapOf<String, Any?>("email" to ""),
    onSubmit = { v, _ -> api.login(v["email"] as String) },
    onError = { t -> snackbar.show("Sign in failed: ${t.message}") },   // <- recommended
)

Same shape on FormikConfig.onError for non-Compose callers, and on KformikForm.onError for the declarative form layer. If you stay inside a scope.launch { form.submit() } coroutine instead of the fire-and-forget path, exceptions propagate naturally and onError is optional.

Working Compose Multiplatform sample in sample-forms-cmp-app/ — 4 screens covering Login / Signup / Profile / Custom+Async on Android, Desktop, and iOS. More patterns in docs/COMPOSE_USAGE.md.

:kformik-compose runs a JVM-host Compose UI test rig (runComposeUiTest) covering state / dirty / isValid / fieldState / enableReinitialize — same :kformik-compose:jvmTest task already wired into CI; no emulator required.

Declarative forms

A higher-level layer in kformik-forms lets you describe the form as Map<String, Field> instead of writing each OutlinedTextField by hand. Same engine underneath; just less code at the call site:

KformikForm(
    fields = mapOf(
        "email"    to Field(type = FieldType.Email,    label = "Email",    required = true, rules = { email() }),
        "password" to Field(type = FieldType.Password, label = "Password", required = true, rules = { minLength(8) }),
        "country"  to Field(
            type = FieldType.Select(listOf(
                SelectOption("us", "United States"),
                SelectOption("eg", "Egypt"),
            )),
            label = ,
        ),
    ),
    onSubmit = { values -> api.register(values) },
)

Renders Material 3 widgets, wires up validation, gates the submit button on . Ten field types ship: , , , , , , , , , . Escape hatches: per-field , custom slot, for form-level error summaries, hook, server-side hydration via / / , and pass-through for + . Full reference in .

Need finer-grained layout (custom containers, dividers between sections, manual submit button)? Drop down to KformikFields(fields, form) — same renderers, but it leaves the surrounding Column and submit-button slot to you. Useful when the default vertical-stack KformikForm layout doesn't fit.

Field.initialValue defaults to the public sentinel FieldDefaultValue (meaning "no explicit value — use the type default"). Pass any value to override; pass null to store an explicit null (useful for Select / Radio to model a "— pick one —" placeholder with SelectOption(value = null, label = "…"), since is ).

The default renderers ship with accessibility baked in: Modifier.toggleable / selectable / selectableGroup for proper role + group announcements; an error text marked as a liveRegion = LiveRegionMode.Polite so screen readers announce newly-appearing validation errors when they land; a programmatic so TalkBack / VoiceOver announce required fields without depending on the visual suffix.

SwiftUI / iOS

FormikIosBridge is a Swift-friendly facade around the same controller. Wrap it in an ObservableObject:

Project layout

kformik/             core KMP library
kformik-compose/     Compose Multiplatform adapter ( /  / iOS)
kformik-forms/        <, > form layer on top of 
kformik-ksp/          processor  typed paths +  (experimental)
sample-forms-cmp-app/  showcase ( screens × , runs on //iOS)
examples/             runnable  examples
docs/                topic-by-topic usage notes

Examples

./gradlew :examples:run -PrunExample=login
./gradlew :examples:run -PrunExample=schema
./gradlew :examples:run -PrunExample=fieldarray
./gradlew :examples:run -PrunExample=wizard

Other example names: nested, async, typed, fieldlevel, dependent, debounced.

Sample app

# Compose Multiplatform showcase — 4 screens covering every important :kformik-forms feature
# (cross-field validation, async username check + debounce, custom rendering via Slider, all 10
# field types). Runs on Android, Desktop JVM, and iOS from one commonMain:
./gradlew :sample-forms-cmp-app:run             # Desktop
./gradlew :sample-forms-cmp-app:installDebug    # Android device / emulator
open sample-forms-cmp-app/iosApp/iosApp.xcodeproj  # iOS — set signing team in Configuration/Config.xcconfig

The CMP showcase ships its own sample-forms-cmp-app/README.md with a feature → screen matrix.

Build

./gradlew :kformik:allTests :kformik:iosSimulatorArm64Test
./gradlew :kformik-compose:jvmTest :kformik-forms:jvmTest :kformik-ksp:test
./gradlew :kformik-compose:assembleRelease :kformik-forms:assembleRelease
./gradlew :sample-forms-cmp-app:assembleDebug :sample-forms-cmp-app:compileKotlinDesktop
./gradlew apiCheck                # binary-compat baselines for every module
./gradlew publishToMavenLocal     # signed artifacts under ~/.m2

All four published modules use kotlin.explicitApi() strict mode — every public declaration must carry an explicit public / internal / private modifier and explicit return type.

Maven Central release process: docs/RELEASE_PROCESS.md.

What's done

What isn't done

Credit

Port of Formik by Jared Palmer. Where Kformik diverges from upstream behavior, the difference is documented in docs/.

License

Apache-2.0. See LICENSE.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

compose-multiplatform★ 19.2k

JetBrainsFacilitates sharing UIs across iOS, Android, Desktop, and Web using a declarative framework. Provides high-performance UI rendering, native APIs access, and desktop-specific extensions. Includes libraries for web UI creation.Shared: compose

compose★ 6.0k

androidxDeclarative UI toolkit enabling programmatic UI via composable functions, offering animations, Material (including Material 3), foundation building blocks, compiler optimizations, runtime state management, and core UI primitives.Shared: compose

lifecycle★ 6.0k

androidxResponding to component state changes: ViewModel and LiveData APIs, Compose integrations, saved-state handling, process-wide state tracking, ReactiveStreams support, and testing utilities.Shared: compose

navigation★ 6.0k

androidxSimplifies navigation between UI destinations via a consistent API, offers type-safe arguments (Safe Args), Compose and fragment integrations, feature-module support, and testing utilities.Shared: compose

navigation3★ 6.0k

androidxDeclarative navigation for Compose UIs, offering runtime and UI modules, navigation graphs, deep-linking, lifecycle-aware back stack handling, and simplified dependency setup.Shared: compose

paging★ 6.0k

androidxGracefully load and display large datasets in RecyclerViews via incremental paging, with support for RxJava, Guava ListenableFutures, testing variants, and Jetpack Compose integration.Shared: compose

Best for	one-off forms; logic that doesn't fit a rule shape; complex conditional branching	reusable validation; multiple forms sharing rules; validation that needs to be inspected
Multi-error per field	hand-rolled with `buildErrors`	built-in via `failFast = false`
Render required-field markers without running validation	manual bookkeeping	`schema.isRequired("email")` directly
Cross-field checks	any Kotlin you want	`custom { v, all -> … all["…"] }`

`required`	`message?`	`required(message)`
`minLength`	`value: Int`, `message?`	`minLength(value, message)`
`maxLength`	`value: Int`, `message?`	`maxLength(value, message)`
`email`	`message?`	`email(message)`
`pattern`	`value: Regex \| String`, `message?`	`pattern(Regex(value), message)`
`min`	`value: Number`, `message?`	`min(value, message)`
`max`	`value: Number`, `message?`	`max(value, message)`

Android (Jetpack Compose)	✅	uses AndroidX Compose runtime under the hood
Desktop JVM (Compose Multiplatform)	✅	works with `compose-jb` desktop projects
iOS (Compose Multiplatform)	✅	`iosX64`, `iosArm64`, `iosSimulatorArm64`
Web / WASM	⏸	not exposed yet (no `wasmJs`/`js` target on this module)

kformik

Kformik

Install

What's in it

Same form, two ways

Built-in rules

Cross-field rules

Nested fields and array indices

When to use which

Multi-error collection

Introspection

Debounced + async validation (v1.7.0+)

Hydration: server-side errors / pre-touched fields

Backend-driven rules (v1.10.0+)

Typed values with KSP

Generating typed paths on demand

Compose

Field-grained recomposition

Fire-and-forget submit + onError

Declarative forms

SwiftUI / iOS

Project layout

Examples

Sample app

Build

What's done

What isn't done

Credit

License

Related libraries

Kformik

Install

What's in it

Same form, two ways

Built-in rules

Cross-field rules

Nested fields and array indices

When to use which

Multi-error collection

Introspection

Debounced + async validation (v1.7.0+)

Hydration: server-side errors / pre-touched fields

Backend-driven rules (v1.10.0+)

Typed values with KSP

Generating typed paths on demand

Compose

Field-grained recomposition

Fire-and-forget submit + onError

Declarative forms

SwiftUI / iOS

Project layout

Examples

Sample app

Build

What's done

What isn't done

Credit

License

Related libraries

Fire-and-forget submit + `onError`

Fire-and-forget submit + `onError`