# Showkase turns your composables into a searchable catalogue at build time

> The Android library solves a specific organisational problem: a Compose codebase accumulates hundreds of components that nobody can find, and a design system that cannot be discovered is not enforced. Showkase solves it with an annotation processor that generates a browser, and the debug-only dependency scoping is the detail that makes it safe to adopt.

**airbnb/Showkase** — 🔦 Showkase is an annotation-processor based Android library that helps you organize, discover, search and visualize Jetpack Compose UI elements

- Repository: https://github.com/airbnb/Showkase
- Website: https://medium.com/airbnb-engineering/introducing-showkase-a-library-to-organize-discover-and-visualize-your-jetpack-compose-elements-d5c34ef01095
- Stars: 2,321 · Forks: 121
- Language: Kotlin
- License: Apache-2.0
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/airbnb-showkase

## The problem is organisational, not technical

The readme states the problem better than most libraries do. Component-based UI toolkits leave a codebase with hundreds of components that are hard to discover, visualise, search and organise. Every company is then forced to build and maintain a preview or browser application by hand. And the reason a design system decays, it says, is discoverability: if people cannot find a component, they will write another one, and consistency suffers as a side effect rather than as the cause. That framing matters because it tells you when the library is worth adding. If your team already knows where everything is, Showkase adds a build step and a dependency for no gain. If your components live across several Gradle modules and new people cannot tell which one to reach for, the generated catalogue removes the need to know the module structure at all. The second claim in the list is about turnaround time: visualising a composable, a colour property or a text style while you are still writing it, rather than discovering that a colour is unreadable in dark mode after it ships. That is a real and cheap win, and the permutations feature exists to serve it.

## An annotation processor, which is why setup is a Gradle dependency plus a root module

The mechanism matters more than the feature list. Showkase runs at build time. The processor reads your annotated elements and generates code, which is why the install is a set of Gradle dependencies rather than a runtime library call. There are three artifacts in the pattern the readme gives. The main artifact is scoped to debug, so the browser and its activity exist only in debug builds. The annotation artifact is scoped to implementation, because the annotations must be visible to the code that uses them but you do not want the processing in release. The processor artifact is scoped to the debug source set as well, so the code generation runs only when you build the variant you are inspecting. That three-way split is the whole safety argument for the library: a processing step that only runs in debug cannot slow release builds or ship generated code in your production artefact. The readme also says the processor is incremental, which it credits with making code generation more performant, which matters because an annotation processor that runs on every build of a large Compose project is a tax on every build rather than a one-off. KDoc on your components is surfaced in the browser, which turns documentation you already write into catalogue metadata.

## Five permutations, and the two that catch real bugs

The readme states that five permutations are auto-created for each composable and names them: a basic example, dark mode, right-to-left, font scaled and display scaled. Two of those are worth their own paragraph because they catch classes of bug that are otherwise found by users. Dark mode catches a hardcoded colour or an insufficient contrast pair, which is the single most common Compose defect. Right-to-left catches hardcoded left and right paddings and text alignment, which also break in a language you may not read. Font scale catches a layout that assumes a fixed text size, and display scale catches one that assumes a fixed pixel dimension. The readme says more are planned, so the set is a starting point rather than a fixed contract. The permutations are generated, not configured per component, which means the coverage is uniform across the catalogue rather than depending on whether someone remembered to add a dark mode preview. That uniformity is the point: a preview you have to write by hand gets written for the three components someone cared about last quarter.

## Install: three scoped dependencies, then annotations, then one root module

The install is four steps and the readme is precise about each. First, add the dependencies to your module's build file, and in a multi-module setup add them to every module whose UI elements should appear in the browser. The recommended scoping puts the main artifact on the debug source set, the annotation artifact on the normal source set, and the processor on the debug source set:

```kotlin
debugImplementation "com.airbnb.android:showkase:1.0.5"
implementation "com.airbnb.android:showkase-annotation:1.0.5"
kspDebug "com.airbnb.android:showkase-processor:1.0.5" or kaptDebug "com.airbnb.android:showkase-processor:1.0.5"
```

Second, annotate what you want to appear. Composables can use the standard Compose preview annotation, which the readme calls first class support, or the Showkase-specific one. Colours take one annotation and text styles another. Third, define an implementation of the root module interface in your root module, annotated as the root. Fourth, start the browser from wherever you like, using a generated helper extension:

```kotlin
startActivity(Showkase.getBrowserIntent(context))
```

Two friction points are named. The readme says you may need to build the app once before the generated helper is available, which is the classic code-generation surprise. And it says the processor defaults to kapt with ksp support added only recently, so if you are on ksp you are on the newer path.

## The repository is bigger than the browser, and the extra modules are the interesting part

The top-level listing shows a project well past the original scope. Alongside the three core modules for the annotations, the processor and the browser, there are modules named for browser testing, processor testing and screenshot testing, with two variants of the browser testing and a sample submodule each. Then there are two separate screenshot testing modules named for two different backends, one for a Paparazzi-based sample and one for a shot-based sample, plus their sample applications. Screenshot tests are a distinct concern from a browser: a browser lets a human look at a component, a screenshot test asserts on a rendered image so a change is caught in continuous integration rather than by whoever remembered to open the app. If you are evaluating this library for design system governance, that is the part that scales, because human review of a catalogue does not survive a team growing. The rest of the repository is ordinary Android project furniture: a Gradle wrapper, a detekt configuration for static analysis, a Gradle properties file, a sample application, and a grep script. The two screenshot files sitting at the repository root, with names containing the codegen marker and a screenshot test index, are generated artefacts committed by accident or by choice, and they are a small sign of what the codegen output looks like.

## Search, grouping, and the features that make a catalogue usable

The features list contains several small things that collectively decide whether anyone uses the browser. Search by name or group is the first, and it is the feature that makes a catalogue of hundreds of components viable rather than merely impressive. Grouping is the second: both annotation forms take a name and a group, and the samples show groups like a material design heading, which implies a taxonomy you agree on rather than a flat list. Constraining a component's height or width is offered through additional annotation parameters, which addresses a real problem, since many composables need a bounded viewport to render sensibly and a browser that renders them unconstrained produces a misleading result. The last item on the list is worth more than it looks: descriptive error messages so users can fix incorrect setup. Misconfiguration in a build-time tool is the failure mode people give up on, and a processor that says what is wrong and where saves an afternoon per mistake. The readme also claims it works across multiple modules, which is a real capability rather than a convenience, since a component library split across Gradle modules is the normal shape of a large Android codebase and the alternative is a browser that can only see one of them.

## Conclusion

Adopt Showkase if your Compose codebase has grown past the point where people can find components by browsing, since discoverability is the failure mode it targets and the generated browser is a cheaper substitute for a bespoke preview app. Do not adopt it if you already have a working design system browser, because the value is entirely in replacing manual maintenance rather than in adding capability. Four things to verify. That you scope the dependency to debug builds, which the readme calls the recommended and practical option and which keeps the processor and browser out of release artefacts. Whether you use ksp or kapt, since the readme says kapt is the default and ksp support was added only recently, and both are declared for the processor artifact. Which Compose version you are on, because the readme badge states compatibility with a specific Compose release. And whether you need the screenshot testing modules, since the repository contains several of them and the browser testing modules are a separate surface from the browser itself. The licence is Apache-2.0, version 1.0.5 was released on 2025-08-05, and the last push was on 2026-03-27.

## FAQ

### How do I add Showkase to an Android project?

Add three scoped Gradle dependencies: the main artifact on the debug source set, the annotation artifact on the normal source set, and the processor on the debug source set using kspDebug or kaptDebug. Then annotate your composables, colours and text styles, define a root module annotated as the root, and start the browser with the generated helper.

### Does Showkase work with the standard Compose preview annotation?

Yes. The readme describes first class support for the standard preview annotation, so components already using it appear in the Showkase browser without being changed, and the Showkase-specific annotation is an alternative for teams that do not already use previews.

### What permutations does Showkase generate?

Five per composable: a basic example, dark mode, a right-to-left layout, a font-scaled variant and a display-scaled variant. The readme says these catch common UI issues early and that more are planned.

### Should the Showkase dependency be debug-only?

The readme presents debug-only as the recommended and practical option for most use cases, with a separate configuration shown for people who want the browser available in release builds too. The processor is scoped to the debug source set, so code generation does not run for release builds.

### What licence is Showkase released under?

Apache-2.0. Version 1.0.5 was released on 2025-08-05, the readme badge states compatibility with a specific Compose release, and the last push to the master branch was on 2026-03-27.

## Sources

- [airbnb/Showkase on GitHub](https://github.com/airbnb/Showkase)
- [License: Apache-2.0](https://github.com/airbnb/Showkase/blob/master/LICENSE)
- [Project website](https://medium.com/airbnb-engineering/introducing-showkase-a-library-to-organize-discover-and-visualize-your-jetpack-compose-elements-d5c34ef01095)
- [README](https://github.com/airbnb/Showkase/blob/master/README.md)
- [Releases](https://github.com/airbnb/Showkase/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/airbnb-showkase