From Imperative to Declarative UI: Airbnb's Epoxy Framework for iOS

In 2016, when Swift was still a brand‑new language, Airbnb began using it extensively in its iOS codebase and started experimenting with more efficient UI development approaches.

The initial experiments were problematic: the Swift‑based UI paradigm caused tens of thousands of crashes and resulted in a terrible developer experience, with a satisfaction score of only –78 (range –100 to 100).

The core issue was the complex indexPath‑based update interface. In the original UI framework, engineers had to write verbose, repetitive code for every indexPath change to achieve smooth animations. For example, inserting a new section after an asynchronous data fetch required manual adjustments to indexPath logic.

Any mistake in indexPath handling could crash the app. While better indexPath management could improve stability, the real goal was to eliminate the need for engineers to maintain this logic manually and to make the UI framework pleasant to use.

This situation highlighted the difference between imperative and declarative programming. Imperative code describes step‑by‑step how to achieve a result, whereas declarative code simply states the desired outcome and lets the system figure out the steps. Epoxy embodies this shift by providing a higher‑level abstraction that automates the tedious update logic.

Epoxy’s solution consists of two parts: (1) a semantic interface that describes page rendering content, and (2) a computation framework that automatically updates the UI based on that description.

Laura Skelton designed the interface around two lightweight models: SectionModel , which holds section configuration and a list of ItemModel objects, and ItemModel , which defines row‑level details such as view construction and property configuration. Because the models are cheap to create, they can be regenerated on every state change.

The view layer was also refactored to use a declarative API. Instead of passing ad‑hoc content and style parameters, views now receive a Content object and a Style object, providing a true semantic interface for view creation and updates.

To efficiently compute differences between two sets of models, Epoxy adopts Paul Heckel’s fast O(N) diffing algorithm (1978), extended to support an “update” operation for modifying existing view instances.

Airbnb’s Android team built a parallel framework, Epoxy for Android, with similar concepts despite platform‑specific differences.

After migrating product detail pages to Epoxy, the team observed smooth animations, zero indexPath‑related crashes, and a jump in developer satisfaction from –78 to +58, prompting a full migration of almost all pages to Epoxy.

Subsequent work replaced imperative UIKit code for top/bottom bars and view‑controller navigation with the same declarative diffing approach, simplifying hierarchy management and reducing boilerplate.

Combined, these declarative interfaces form a complete declarative UI framework, which Airbnb open‑sourced at github.com/airbnb/epoxy-ios .

Building on this foundation, the team explored unidirectional data flow, allowing the entire UI to be derived from a single immutable state object.

The article also mentions SwiftUI, Apple’s declarative UI framework, noting its conceptual similarity to Epoxy and the team’s interest in future migration when the timing is right.