Skip to main content

Orbit Multiplatform

Logo

Orbit is a Redux/MVI-like library - but without the baggage. It's so simple we think of it as MVVM+.

Documentation​

Getting started​

Download

implementation("org.orbit-mvi:orbit-core:<latest-version>")
// or, if on Android:
implementation("org.orbit-mvi:orbit-viewmodel:<latest-version>")
// If using Jetpack Compose include
implementation("org.orbit-mvi:orbit-compose:<latest-version>")

// Tests
testImplementation("org.orbit-mvi:orbit-test:<latest-version>")

Define the contract​

data class CalculatorState(
    val total: Int = 0
)

sealed class CalculatorSideEffect {
    data class Toast(val text: String) : CalculatorSideEffect()
}

The state and side effect objects must be comparable and we also recommend they be immutable. We suggest using a mix of data classes, sealed classes and objects.

Create the ViewModel​

  1. Implement the ContainerHost interface
  2. Override the container field and use the ViewModel.container factory function to build an Orbit Container in your ContainerHost
class CalculatorViewModel: ContainerHost<CalculatorState, CalculatorSideEffect>, ViewModel() {

    // Include `orbit-viewmodel` for the factory function
    override val container = container<CalculatorState, CalculatorSideEffect>(CalculatorState())

    fun add(number: Int) = intent {
        postSideEffect(CalculatorSideEffect.Toast("Adding $number to ${state.total}!"))

        reduce {
            state.copy(total = state.total + number)
        }
    }
}

We have used an Android ViewModel as the most common example, but it's not required. You can host an Orbit Container in a simple Kotlin class if you wish. This makes it possible to use in UI independent components as well as Kotlin Multiplatform projects.

Connect to the ViewModel in your Activity or Fragment​

On Android, we expose an easy one-liner function to connect your UI to the ViewModel. Alternatively, you can use the Container's Flows directly.

class CalculatorActivity: AppCompatActivity() {

    // Example of injection using koin, your DI system might differ
    private val viewModel by viewModel<CalculatorViewModel>()

    override fun onCreate(savedState: Bundle?) {
        ...
        addButton.setOnClickListener { viewModel.add(1234) }

        // Use the one-liner from the orbit-viewmodel module to observe when
        // Lifecycle.State.STARTED
        viewModel.observe(state = ::render, sideEffect = ::handleSideEffect)

        // Or observe the streams directly
        lifecycleScope.launch {
            lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
                launch {
                    viewModel.container.stateFlow.collect { render(it) }
                }
                launch {
                    viewModel.container.sideEffectFlow.collect { handleSideEffect(it) }
                }
            }
        }
    }

    private fun render(state: CalculatorState) {
        ...
    }

    private fun handleSideEffect(sideEffect: CalculatorSideEffect) {
        when (sideEffect) {
            is CalculatorSideEffect.Toast -> toast(sideEffect.text)
        }
    }
}