Getting Started

Gradle/Java

Adding Litho to your Project

We publish the Litho artifacts to Bintray's JCenter. To include Litho to your Android project, make sure you include the reference to the repository in your build.gradle file:

repositories {
  jcenter()
}

Then add the dependencies like this:

dependencies {
  // ...
  // Litho
  implementation 'com.facebook.litho:litho-core:0.42.0'
  implementation 'com.facebook.litho:litho-widget:0.42.0'
  annotationProcessor 'com.facebook.litho:litho-processor:0.42.0'

  // SoLoader
  implementation 'com.facebook.soloader:soloader:0.10.4'

  // For integration with Fresco
  implementation 'com.facebook.litho:litho-fresco:0.42.0'

  // For testing
  testImplementation 'com.facebook.litho:litho-testing:0.42.0'
}

Adding Sections to your Project

Litho comes with an optional library called Sections for declaratively building lists. You can include Sections by adding the following additional dependencies to your build.gradle file:

dependencies {

  // Sections
  implementation 'com.facebook.litho:litho-sections-core:0.42.0'
  implementation 'com.facebook.litho:litho-sections-widget:0.42.0'
  compileOnly 'com.facebook.litho:litho-sections-annotations:0.42.0'

  annotationProcessor 'com.facebook.litho:litho-sections-processor:0.42.0'
}

Using Snapshot releases

caution

This will break and may set your house on fire. Snapshots are unsigned and automatically published by our CI system. Use them for testing purposes only.

First, add the Sonatype Snapshots repository to your gradle config:

repositories {
  maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
}

Then you can access the snapshot versions of all Litho artifacts that we publish:

dependencies {
  // ...
  // Litho
  implementation 'com.facebook.litho:litho-core:0.43.0-SNAPSHOT'
  implementation 'com.facebook.litho:litho-widget:0.43.0-SNAPSHOT'
  annotationProcessor 'com.facebook.litho:litho-processor:0.43.0-SNAPSHOT'

  // SoLoader
  implementation 'com.facebook.soloader:soloader:0.10.4'

  // For integration with Fresco
  implementation 'com.facebook.litho:litho-fresco:0.43.0-SNAPSHOT'

  // For testing
  testImplementation 'com.facebook.litho:litho-testing:0.43.0-SNAPSHOT'
}

Gradle/Kotlin

Adding Litho to your Kotlin Project

caution

Kotlin support for Litho is experimental at this point.

In order to use Litho's annotation processor, you need to opt in to the Kotlin KAPT plugin at the top of your application's build.gradle file:

apply plugin: 'kotlin-kapt'

We publish the Litho artifacts to Bintray's JCenter. To include Litho to your Android project, make sure you include the reference to the repository in your build.gradle file:

repositories {
  jcenter()
}

Then add the dependencies like this:

dependencies {
  // ...
  // Litho
  implementation 'com.facebook.litho:litho-core:0.42.0'
  implementation 'com.facebook.litho:litho-widget:0.42.0'
  kapt 'com.facebook.litho:litho-processor:0.42.0'

  // SoLoader
  implementation 'com.facebook.soloader:soloader:0.10.4'

  // For integration with Fresco
  implementation 'com.facebook.litho:litho-fresco:0.42.0'

  // For testing
  testImplementation 'com.facebook.litho:litho-testing:0.42.0'
}

Adding Sections to your Project

Litho comes with an optional library called Sections for declaratively building lists. You can include Sections by adding the following additional dependencies to your build.gradle file:

dependencies {

  // Sections
  implementation 'com.facebook.litho:litho-sections-core:0.42.0'
  implementation 'com.facebook.litho:litho-sections-widget:0.42.0'
  compileOnly 'com.facebook.litho:litho-sections-annotations:0.42.0'

  kapt 'com.facebook.litho:litho-sections-processor:0.42.0'
}

Using Snapshot releases

caution

This will break and may set your house on fire. Snapshots are unsigned and automatically published by our CI system. Use them for testing purposes only.

First, add the Sonatype Snapshots repository to your gradle config:

repositories {
  maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
}

Then you can access the snapshot versions of all Litho artifacts that we publish:

dependencies {
  // ...
  // Litho
  implementation 'com.facebook.litho:litho-core:0.43.0-SNAPSHOT'
  implementation 'com.facebook.litho:litho-widget:0.43.0-SNAPSHOT'

  kapt 'com.facebook.litho:litho-processor:0.43.0-SNAPSHOT'

  // SoLoader
  implementation 'com.facebook.soloader:soloader:0.10.4'

  // For integration with Fresco
  implementation 'com.facebook.litho:litho-fresco:0.43.0-SNAPSHOT'

  // For testing
  testImplementation 'com.facebook.litho:litho-testing:0.43.0-SNAPSHOT'
}

Buck/Java

Adding Litho to your Project

You can include Litho to your Android project via Buck by adding the following to your BUCK file:

android_prebuilt_aar(
    name = "litho",
    aar = ":litho-core.aar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-core.aar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-core:aar:0.42.0",
)

prebuilt_jar(
    name = "litho-annotation",
    binary_jar = ":litho-annotation.jar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-processor.jar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-processor:jar:0.42.0",
)

prebuilt_jar(
    name = "litho-processor",
    binary_jar = ":litho-processor.jar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-annotation.jar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-annotation:jar:0.42.0",
)

android_prebuilt_aar(
    name = "litho-widget",
    aar = ":litho-widget.aar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-widget.aar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-widget:aar:0.42.0",
)

android_library(
    ...
    # Your target here
    ...
    annotation_processor_deps = [
        ":litho-annotation",
        ":litho-processor",
    ],
    annotation_processors = [
        "com.facebook.litho.specmodels.processor.ComponentsProcessor",
    ],
    provided_deps = [
        "litho-annotation",
    ],
    deps = [
        ":litho",
        ":litho-widget",
        ...
    ]
)

Adding Sections to your Project

Litho comes with an optional library called Sections for declaratively building lists. You can include Sections by adding the following additional dependencies to your BUCK file:

android_prebuilt_aar(
    name = "litho-sections",
    aar = ":litho-sections-core.aar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-sections-core.aar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-sections-core:aar:0.42.0",
)

prebuilt_jar(
    name = "litho-sections-annotation",
    binary_jar = ":litho-sections-annotation.jar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-sections-processor.jar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-sections-processor:jar:0.42.0",
)

prebuilt_jar(
    name = "litho-sections-processor",
    binary_jar = ":litho-sections-processor.jar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-sections-annotation.jar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-sections-annotation:jar:0.42.0",
)

android_prebuilt_aar(
    name = "litho-sections-widget",
    aar = ":litho-sections-widget.aar",
    visibility = ["PUBLIC"],
)

remote_file(
    name = "litho-sections-widget.aar",
    sha1 = "sha1here",
    url = "mvn:com.facebook.litho:litho-sections-widget:aar:0.42.0",
)

Then modify your android_library target as such:

android_library(
    ...
    # Your target here
    ...
    annotation_processor_deps = [
        ":litho-annotation",
        ":litho-processor",
        ":litho-sections-annotations",
        ":litho-sections-processor",
    ],
    annotation_processors = [
        "com.facebook.litho.specmodels.processor.ComponentsProcessor",
        "com.facebook.litho.specmodels.processor.sections.SectionsComponentProcessor",
    ],
    provided_deps = [
        "litho-annotations",
        "litho-sections-annotations",
    ],
    deps = [
        ":litho",
        ":litho-widget",
        ":litho-sections",
        ":litho-sections-widget",
        ...
    ]
)

Testing/Java

Testing your Installation

You can test your install by adding a view created with Litho to an activity.

First, initialize SoLoader. Litho has a dependency on SoLoader to help load native libraries provided by the underlying layout engine, Yoga. Your Application class is a good place to do this:

MyApplication.java

public class MyApplication extends Application {

  @Override
  public void onCreate() {
    super.onCreate();

    SoLoader.init(this, false);
  }
}

Then, add a predefined Litho Text widget to an activity that displays "Hello World!":

MyActivity.java

import com.facebook.litho.ComponentContext;
import com.facebook.litho.LithoView;

public class MyActivity extends Activity {

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    final ComponentContext c = new ComponentContext(this);

    final LithoView lithoView = LithoView.create(
        this /* context */,
        Text.create(c)
            .text("Hello, World!")
            .textSizeDip(50)
            .build());

    setContentView(lithoView);
  }
}

Now, when you run the app you should see "Hello World!" displayed on the screen.

Testing/Kotlin

Testing your Installation

You can test your install by adding a view created with Litho to an activity.

First, initialize SoLoader. Litho has a dependency on SoLoader to help load native libraries provided by the underlying layout engine, Yoga. Your Application class is a good place to do this:

MyApplication.kt

class MyApplication: Application() {

  override fun onCreate() {
    super.onCreate()
    SoLoader.init(this, false)
  }
}

Then, add a predefined Litho Text widget to an activity that displays "Hello World!":

MyActivity.kt

import com.facebook.litho.ComponentContext
import com.facebook.litho.LithoView

class MyActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val c = ComponentContext(this)

    val lithoView = LithoView.create(
        this /* context */,
        Text.create(c)
            .text("Hello, World!")
            .textSizeDip(50)
            .build())

    setContentView(lithoView)
  }
}

Now, when you run the app you should see "Hello World!" displayed on the screen.