DSL library for creating state machines and statecharts. Supports event-based transitions, reactive listening, nested and parallel states, typesafe transitions, undo transitions, and exports to diagrams. Zero dependencies.
A powerful Kotlin Multiplatform state machine library with clean DSL syntax
and first-class Kotlin Coroutines support
📖 Documentation | 📚 KDoc | 🔌 IntelliJ Plugin | 🚀 Quick Start | 🧪 Samples | 💾 Install | 💬 Discussions |
KStateMachine lets you model complex application logic as a finite state machine or statechart using an expressive Kotlin DSL. It runs on every Kotlin Multiplatform target, integrates seamlessly with Kotlin Coroutines, and has zero mandatory dependencies.
🔴 Red — stop!
→ switching…
leaving red
🟡 Yellow — get ready
🟢 Green — go!
✅ Done
Integration
| Feature |
|---|
State management
Tooling
KStateMachine Visual is an IntelliJ IDEA plugin that visualizes and navigates your state machines straight from Kotlin source — no runtime required.
Install: Settings → Plugins → Marketplace → search KStateMachine Visual
See the plugin documentation page for the full feature reference and manual install instructions.
[!IMPORTANT] Full documentation lives at kstatemachine.github.io/kstatemachine
KDoc for every class: kstatemachine.github.io/kstatemachine/kdoc
If KStateMachine saves you time, please consider supporting the project:
Full app samples and 20+ runnable focused code samples are listed on the Samples page in the documentation.
KStateMachine is published to Maven Central and JitPack.
dependencies {
// Core (zero dependencies)
implementation("io.github.nsk90:kstatemachine:<Tag>")
// + Kotlin Coroutines integration (optional)
implementation("io.github.nsk90:kstatemachine-coroutines:<Tag>")
// + kotlinx.serialization for state persistence (optional)
implementation("io.github.nsk90:kstatemachine-serialization:<Tag>")
}
Replace <Tag> with the current version shown in the Maven Central badge above.
See the full install guide for Gradle Kotlin DSL,
Groovy DSL, and JitPack variants.
./gradlew build # build all modules
./gradlew :tests:jvmTest # run all tests (JVM target)
Or open in IntelliJ IDEA and run from there.
The library is in stable phase — but feature proposals and pull requests are welcome!
Please read CONTRIBUTING.md before submitting.
| Channel | Best for |
|---|---|
| Slack |
When asking on other platforms, include a link to this repo or use the #kstatemachine tag.
Licensed under the permissive Boost Software License.
// Events
object SwitchEvent : Event
// States
sealed class States : DefaultState() {
object RedState : States()
object YellowState : States()
object GreenState : States(), FinalState // machine stops here
}
fun main() = runBlocking {
val machine = createStateMachine(scope = this) {
addInitialState(RedState) {
onEntry { println("🔴 Red — stop!") }
onExit { println(" leaving red") }
transition<SwitchEvent> {
targetState = YellowState
onTriggered { println(" → switching…") }
}
}
addState(YellowState) {
onEntry { println("🟡 Yellow — get ready") }
transition<SwitchEvent>(targetState = GreenState)
}
addFinalState(GreenState) {
onEntry { println("🟢 Green — go!") }
}
onFinished { println("✅ Done") }
}
machine.processEvent(SwitchEvent) // Red → Yellow
machine.processEvent(SwitchEvent) // Yellow → Green (finished)
}
| Description |
|---|
| Kotlin DSL | Declarative, readable structure; plain API also available |
| Kotlin Coroutines | Suspending functions in listeners and guards; fully optional |
| Kotlin Multiplatform | JVM, Android, iOS, JS, Wasm, Native |
| Zero dependencies | Core artifact depends only on the Kotlin stdlib |
| Feature | Description |
|---|
| Event-based | Transitions fire in response to events |
| Reactive listeners | Observe machines, states, state groups, and transitions |
| Guarded & conditional transitions | Dynamic target state computed at runtime |
| Nested states | Full statechart hierarchy with cross-level transitions |
| Composed state machines | Embed one machine as a child state of another |
| Pseudo states | History, redirect, and other behavioural helpers |
| Typesafe transitions | Carry typed data from event to target state |
| Parallel states | Run orthogonal regions simultaneously |
| Fork & Join | Synchronize concurrent orthogonal regions (UML fork/join pseudo-states) |
| Undo transitions | Navigate back like a stack-based FSM |
| Feature | Description |
|---|
| IntelliJ Plugin | Visualise, navigate, and export state machines directly from your IDE — no runtime needed |
| Export | Generate PlantUML or Mermaid diagrams from your machine definition |
| Persist & restore | Two strategies: event recording (full replay) or state snapshot (captureSavedStateConfig) — both serialisable via kotlinx.serialization |
| Testing helpers | startFrom(state) bypasses normal init, enabling focused unit tests |
| Library comparison | Side-by-side feature matrix vs FlowRedux, Tinder StateMachine, and Spring State Machine |
#kstatemachine| Questions & discussions |
| GitHub Discussions | Questions & longer discussions |
| GitHub Issues | Bug reports & feature requests |
Surfaced from shared tags and platforms — no rankings paid for.