Showkase

Showkase Version Compatible with Compose

Showkase is an annotation-processor based Android library that helps you organize, discover, search and visualize Jetpack Compose UI elements. With minimal configuration it generates a UI browser that helps you easily find your components, colors & typography. It also renders your components in common situations like dark mode, right-to-left layouts, and scaled fonts which help in finding issues early.

Why should you use Showkase?

  • When using component based UI toolkits (like React, Compose, Flutter, etc), our codebase often ends up with hundreds of components that are hard to discover, visualize, search and organize.
  • Showkase eliminates the manual work of maintaining a UI preview/browser app that each company is forced to build in order to maintain their design system.
  • Since all the available UI elements are now easily searchable and discoverable, there is better reuse of UI elements in your repo. This makes it useful for maintaining consistency across your app. The biggest problem for enforcing a design system is discoverability and Showkase hopefully solves that problem for your team.
  • It allows you to quickly visualize @Composable components, Color properties and TextStyle (Typography) as you are building them. The goal is to improve the turnaround time in creating production-ready UI elements.
  • Showkase aids in catching common UI issues early with the help of auto-generated permutations of your components.

Features

  • Super simple setup
  • Support for visualizing composables(@ShowkaseComposable), colors(@ShowkaseColor) & typography(@ShowkaseTypography).
  • First class support for @Preview annotation. If you are already using @Preview for previews in Android Studio, using Showkase is even easier as all those components are included in the Showkase browser.
  • Support for top level, class, object & companion object functions and properties to be annotated with the Showkase annotations.
  • 5 Permutations are auto created for each composable (Basic Example, Dark Mode, RTL, Font Scaled, Display Scaled. Look in the gif above for examples)’. More to be added in the future!
  • Support for searching a Showkase UI element by name or group.
  • KDoc support that shows the documentation that you added for a component in the Showkase browser.
  • Multi-module support for showcasing UI elements across multiple modules.
  • Support for constraining a component with a custom height/width using additional parameters in the annotation.
  • Descriptive error messages so that the users of the library can fix any incorrect setup.
  • Incremental annotation processor that makes the code-gen more performant.

Installation

Using Showkase is straightforward and takes just a couple of minutes to get started.

Step 1: Add the dependency to your module’s build.gradle file. If you have a multi-module setup, add this dependency to all the modules with UI elements that should be displayed inside the Showkase browser.

implementation "com.airbnb.android:showkase:1.0.0-beta03"
kapt "com.airbnb.android:showkase-processor:1.0.0-beta03"

Step 2: Add the relevant annotations for every UI element that should be a part of the Showkase browser.

For @Composable components, you can either use the @Preview annotation that Compose comes with or use the @ShowkaseComposable annotation:

@Preview(name = "Custom name for component", group = "Custom group name")
@Composable
fun MyComponent() { ... }

// or

@ShowkaseComposable(name = "Name of component", group = "Group Name")
@Composable
fun MyComponent() { ... }

For Color properties, you can add the @ShowkaseColor annotation to the field:

@ShowkaseColor(name = "Primary Color", group = "Material Design")
val primaryColor = Color(0xFF6200EE)

For TextStyle properties that are useful for typography, you can add the @ShowkaseTypography annotation to the field:

@ShowkaseTypography(name = "Custom name for style", group = "Custom group name")
val h1 = TextStyle(
    fontWeight = FontWeight.Light,
    fontSize = 96.sp,
    letterSpacing = (-1.5).sp
)

Step 3: Define an implementation of the ShowkaseRootModule interface in your root module. If your setup involves only a single module, add this implementation in that module. Ensure that this implementation is also annotated with the @ShowkaseRoot annotation.

@ShowkaseRoot
class MyRootModule: ShowkaseRootModule

Step 4: Showkase is now ready for use! Showkase comes with an Activity that you need to start for accessing the UI browser. Typically you would start this activity from the debug menu of your app but you are free to start this from any place you like! A nice helper extension function getBrowserIntent is generated for you so you might have to build the app once before it’s available for use. Just start the intent and that’s all you need to do for accessing Showkase!

startActivity(Showkase.getBrowserIntent(context))

Documentation

1. @ShowkaseComposable

Used to annotate @Composable functions that should be displayed inside the Showkase browser. If you are using the @Preview annotation with your @Composable function already then you don’t need to use this annotation. Showkase has first class support for @Preview.

Here’s how you would use it with your @Composable function:

@ShowkaseComposable(name = "Name", group = "Group")
@Composable
fun MyComposable() {
    .......
    .......
}

Name and group are optional. Look at the properties section to understand the behavior when you don’t pass any properties.

Note: Make sure that you add this annotation to only those functions that meet the following criteria:

  • Functions that don’t have any parameters
  • If it does have a parameter, it has to be annotated with @PreviewParameter that is provided a PreviewParameterProvider implementation.

This is identical to how @Preview works in Compose as well so Showkase just adheres to the same rules.

<div class="highlight highlight-source-kotlin position-relative" data-snippet-clipboard-copy-content="
// Consider a simple data class
data class Person(
val name: String,
val age: Int
)

// In order to pass a person object as a parameter to our composable function, we will annotate
// our parameter with `@PreviewParameter` and pass a `PreviewParameterProvider` implementation.
@ShowkaseComposable(name = " Name", group="Group" ) or @Preview(name="Name" , group="Group" ) @Composable fun MyComposable( @PreviewParameter(provider = ParameterProvider::class) person: Person ) { … } class ParameterProvider : PreviewParameterProvider {
override val values: Sequence
get() = sequenceOf(
Person(“John”, 12),
Person(“Doe”, 20)
)
override val count: Int
get() = super.count
}
// Since we return 2 objects through our ParameterProvider, Showkase will create 2 previews
// for this single composable function. Each preview will have it’s own parameter that’s passed
// to it – Person(“John”, 12) for the first preview and Person(“Doe”, 20) for the second one.
// This is an effective way to preview your composables against different sets of data.
“>

// Consider a simple data class
data class Person(
    val name: String,
    val age: Int
)

// In order to pass a person object as a parameter to our composable function, we will annotate 
// our parameter with `@PreviewParameter` and pass a `PreviewParameterProvider` implementation.
@ShowkaseComposable(name = "Name", group = "Group") or @Preview(name = "Name", group = "Group")
@Composable
fun MyComposable(
    @PreviewParameter(provider = ParameterProvider::class) person: Person
) {
    ...
}

class ParameterProvider : PreviewParameterProvider<Person> {
    override val values: Sequence<Person>
        get() = sequenceOf(
            Person("John", 12),
            Person("Doe", 20)
        )

    override val count: Int
        get() = super.count
}

// Since we return 2 objects through our ParameterProvider, Showkase will create 2 previews 
// for this single composable function. Each preview will have it's own parameter that's passed 
// to it - Person("John", 12) for the first preview and Person("Doe", 20) for the second one. 
// This is an effective way to preview your composables against different sets of data.