Litho: Facebook’s Declarative Android UI Framework – Overview, Usage, and Principles

What is Litho? Litho is a declarative framework introduced by Facebook for building efficient Android user interfaces, especially complex RecyclerView‑based lists. It replaces traditional Android views with components, where a component is a function that receives immutable props and returns a UI hierarchy.

Architecture layers

Application layer: the top‑level Android app integration point.

Specification layer (API): declarative APIs annotated to generate Flexbox‑compliant layouts.

Layout layer: uses mountable components, layout components, and Flexbox components; each component is a self‑contained module similar to React components.

Layout measurement: Yoga performs asynchronous or synchronous measurement, flattening the layout.

Layout rendering: supports rendering via View or lightweight Drawable for further flattening.

Litho usage vs. traditional Android

Traditional Android defines UI in XML files (e.g., <TextView .../> ) and inflates them in an Activity . Litho abandons XML and builds UI directly in Java/Kotlin using components.

<?xml version="1.0" encoding="utf-8"?>
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Hello World"
    android:textAlignment="center"
    android:textColor="#666666"
    android:textSize="40dp"/>

Equivalent Litho code:

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ComponentContext c = new ComponentContext(this);
        Component component = Text.create(c)
            .text("Hello World")
            .textSizeDip(40)
            .textColor(Color.parseColor("#666666"))
            .textAlignment(Layout.Alignment.ALIGN_CENTER)
            .build();
        LithoView view = LithoView.create(c, component);
        setContentView(view);
    }
}

Component specifications

Litho provides two spec types:

LayoutSpec: defines layout components using @LayoutSpec and @OnCreateLayout . Example:

@LayoutSpec
class HelloComponentSpec {
    @OnCreateLayout
    static Component onCreateLayout(ComponentContext c, @Prop String name) {
        return Column.create(c)
            .child(Text.create(c).text("Hello, " + name).textSizeRes(R.dimen.my_text_size).textColor(Color.BLACK).paddingDip(ALL, 10))
            .child(Image.create(c).drawableRes(R.drawable.welcome).scaleType(ImageView.ScaleType.CENTER_CROP))
            .build();
    }
}

MountSpec: generates mountable components that render a View or Drawable . It must implement lifecycle methods such as @OnPrepare , @OnMeasure , @OnCreateMountContent , @OnMount , @OnBind , @OnUnbind , and @OnUnmount .

Props and State

Props are immutable inputs annotated with @Prop . State is mutable but controlled internally; it can be initialized via a Prop.

@MountSpec
class MyComponentSpec {
    @OnPrepare
    static void onPrepare(ComponentContext c) { /* ... */ }
    @OnMount
    static void onMount(ComponentContext c, SomeDrawable drawable, @Prop(optional = true) String prop1, @Prop int prop2) { /* ... */ }
}

Key features and principles

Declarative components: UI is described by immutable component trees, similar to React.

Asynchronous layout: Layout measurement and calculation are performed off the UI thread using Yoga, reducing jank in complex RecyclerViews.

Flattened view hierarchy: Yoga converts Flexbox layouts to absolute positions, and Litho often renders with Drawable instead of View , cutting down recursion and memory.

Fine‑grained reuse: Individual component units are cached and reused, leading to lower memory usage compared with native RecyclerView’s view‑type pooling.

Drawable fallback strategy: When interaction is required (click listeners, focus, tags, etc.), Litho automatically falls back to a View .

Performance results (Meituan case study)

Meituan integrated Litho as the rendering engine for its dynamic layout system (MTFlexbox). Real‑world measurements on a Vivo X20 showed over 30 MB memory reduction and smoother FPS due to async layout.

Conclusion

Litho brings React‑style declarative UI and significant performance gains to Android, but it requires custom component development and lacks real‑time preview. Wrapping Litho as a Flexbox rendering engine, as Meituan did, offers a practical compromise.