Renders markdown content with easy setup, cross-platform support, and lightweight performance. Customizes styles, extended spans, and annotated strings. Integrates image loading and allows custom components.
Render Markdown as native Compose UI — one API, every platform.
Quickstart • Showcase • Reference • Migration • Changelog
1 — Add the dependency. Pick the module matching your Material theme:
dependencies {
implementation("com.mikepenz:multiplatform-markdown-renderer:0.43.0")
implementation("com.mikepenz:multiplatform-markdown-renderer-m3:0.43.0") // or -m2
}
2 — Render. Import Markdown from com.mikepenz.markdown.m3 (or .m2):
import com.mikepenz.markdown.m3.Markdown
Markdown(
"""
# Hello Markdown
- Bullet points
- **Bold** and *italic* text
[Check out this link](https://github.com/mikepenz/multiplatform-markdown-renderer)
""".trimIndent()
)
3 — Hoist the parse for anything non-trivial. rememberMarkdownState parses asynchronously and
survives recomposition:
val markdownState = rememberMarkdownState(markdown)
Markdown(markdownState)
Full configuration — custom components, image loading, syntax highlighting, extended spans — is in the Reference below.
Every panel below is a Paparazzi snapshot of the sample app, recorded from
ReadmeShowcasePreviews.kt
and refreshed by ./gradlew :sample:android:recordPaparazzi :sample:android:copyReadmeArt.
Left: the default Markdown composable — no configuration.
Right: markdownComponents(codeFence = ...) wired to
MarkdownHighlightedCodeFence from the -code module.
Left: GFM tables and GitHub alerts, rendered without opt-in.
Right: markdownComponents(checkbox = ...), markdownColor()
and markdownExtendedSpans with RoundedCornerSpanPainter.
Choose the appropriate configuration based on your project type:
For multiplatform projects, add these dependencies to your build.gradle.kts:
For JVM-only projects, add this dependency:
dependencies {
implementation("com.mikepenz:multiplatform-markdown-renderer-jvm:${version}")
}
For Android-only projects, add this dependency:
dependencies {
implementation("com.mikepenz:multiplatform-markdown-renderer-android:${version}")
}
[!IMPORTANT] Since version 0.13.0, the core library does not depend on a Material theme. You must include either the
-m2or-m3module to get access to the default styling.
The most basic usage is to simply pass your markdown string to the Markdown composable:
// In your composable (use the appropriate Markdown implementation for your theme)
Markdown(
"""
# Hello Markdown
This is a simple markdown example with:
- Bullet points
- **Bold text**
- *Italic text*
[Check out this link](https://github.com/mikepenz/multiplatform-markdown-renderer)
""".trimIndent()
)
[!NOTE]
Import eithercom.mikepenz.markdown.m3.Markdownfor Material 3 orcom.mikepenz.markdown.m2.Markdownfor Material 2 themed applications.
[!NOTE]
By default, when the markdowncontentchanges, the component will display a loading state while parsing the new content. To keep the previous content visible during updates and avoid showing the loading state, setretainStatetotrue.
For content that arrives in chunks — an LLM response, a network stream — use
rememberStreamingMarkdownState(). It is append-only: each append re-parses only the unstable
tail of the document rather than the whole string.
val streamingMarkdownState = rememberStreamingMarkdownState()
LaunchedEffect(chunkFlow) {
chunkFlow.collect { chunk -> streamingMarkdownState.append(chunk) }
}
Markdown(streamingMarkdownState = streamingMarkdownState)
If the chunks already arrive as a Flow<String>, collectAsStreamingMarkdownState() does the
collecting for you:
val streamingMarkdownState = chunkFlow.collectAsStreamingMarkdownState()
Markdown(streamingMarkdownState = streamingMarkdownState)
StreamingMarkdownState.snapshot exposes the split as a StateFlow<Snapshot> with stableAst and
unstableAstTail, if you need to observe it. See StreamingMarkDownPage in the sample for a
working example including render statistics.
To configure image loading, the library offers different implementations, to offer great flexibility
for the respective integration.
After adding the dependency, the chosen image transformer implementation has to be passed to the
Markdown API.
[!NOTE]
Please refer to the official documentation for the specific image loading integration you are using (e.g., coil3) on how to adjust its behavior.
// Offers coil3 (Coil3ImageTransformerImpl)
implementation("com.mikepenz:multiplatform-markdown-renderer-coil3:${version}")
Markdown(
MARKDOWN,
imageTransformer = Coil3ImageTransformerImpl,
)
// Offers coil2 (Coil2ImageTransformerImpl)
implementation("com.mikepenz:multiplatform-markdown-renderer-coil2:${version}")
Markdown(
MARKDOWN,
imageTransformer = Coil2ImageTransformerImpl,
)
The library (introduced with 0.27.0) offers optional support for syntax highlighting via
the Highlights project.
This support is not included in the core, and can be enabled by adding the
multiplatform-markdown-renderer-code
dependency.
implementation("com.mikepenz:multiplatform-markdown-renderer-code:${version}")
Once added, the Markdown has to be configured to use the alternative code highlighter.
// Use default color scheme
Markdown(
MARKDOWN,
components = markdownComponents(
codeBlock = highlightedCodeBlock,
codeFence = highlightedCodeFence,
)
)
// ADVANCED: Customize Highlights library by defining different theme
val isDarkTheme = isSystemInDarkTheme()
val highlightsBuilder = remember(isDarkTheme) {
Highlights.Builder().theme(SyntaxThemes.atom(darkMode = isDarkTheme))
}
Markdown(
MARKDOWN,
components = markdownComponents(
codeBlock = {
MarkdownHighlightedCodeBlock(
content = it.content,
node = it.node,
highlightsBuilder = highlightsBuilder,
showHeader = true, // optional enable header with code language + copy button
)
},
codeFence = {
MarkdownHighlightedCodeFence(
content = it.content,
node = it.node,
highlightsBuilder = highlightsBuilder,
showHeader = ,
)
},
)
)
This library uses the following key dependencies:
This free, open source software was made possible by a group of volunteers who put many hours of hard work into it. See the CONTRIBUTORS.md file for details.
Big thanks to Erik Hellman and his awesome article on Rendering Markdown with Jetpack Compose, and the related source MarkdownComposer.
Also huge thanks to Saket Narayan for his great work on the extended-spans project, which was ported into this project to make it multiplatform.
Copyright for portions of the code are held by [Erik Hellman, 2020] as part of project MarkdownComposer under the MIT license. All other copyright for project multiplatform-markdown-renderer are held by [Mike Penz, 2023] under the Apache License, Version 2.0.
Copyright 2026 Mike Penz
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
| 🧩 Every platform | Android, iOS, Desktop (JVM), Web (Wasm / JS) and macOS from one commonMain call. |
| ⚡ Async by default | rememberMarkdownState parses off the composition; retainState = true keeps content visible while re-parsing. |
| 🎨 Material 2 and 3 | Themed defaults from -m2 / -m3; override with markdownColor() and markdownTypography(). |
| 🧱 Every element overridable | MarkdownComponents maps each AST node to a @Composable you control. |
| 📊 Full GFM | Tables, task lists, strikethrough, autolinks and GitHub alerts, out of the box. |
| 📡 Built for streaming | rememberStreamingMarkdownState() appends chunks and re-parses only the unstable tail. |
| Topic |
|---|
| Setup | Gradle coordinates for multiplatform, JVM and Android |
| Usage | The Markdown composable, state hoisting, and every customisation hook |
| Streaming | Appending chunks from an LLM or network stream |
| Image Loading | Coil 2 and Coil 3 transformers |
| Syntax Highlighting | The optional -code module |
| Dependencies | What this library builds on |
| Migration | Breaking changes between versions |
| License | Apache 2.0 |
dependencies {
// Core library
implementation("com.mikepenz:multiplatform-markdown-renderer:${version}")
// Choose ONE of the following based on your Material theme:
// For Material 2 themed apps
implementation("com.mikepenz:multiplatform-markdown-renderer-m2:${version}")
// OR for Material 3 themed apps
implementation("com.mikepenz:multiplatform-markdown-renderer-m3:${version}")
}
rememberMarkdownStateFor better performance, especially with larger markdown content, use rememberMarkdownState or move
the parsing of the markdown into your viewmodel:
val markdownState = rememberMarkdownState(markdown)
Markdown(markdownState)
[!NOTE]
Since version 0.33.0, markdown content is parsed asynchronously by default, resulting in a loading state being displayed prior to the parsing result. TherememberMarkdownStatefunction offers the ability to require immediate parsing with theimmediateparameter, but this is not advised as it might block the composition of the UI.
// Default asynchronous parsing (recommended)
val markdownState = rememberMarkdownState(markdown)
// Force immediate parsing (not recommended)
val markdownState = rememberMarkdownState(markdown, immediate = true)
By default, when the markdown content changes, the component shows a loading state while parsing the
new content. You can use the retainState parameter to keep the previous rendered content visible
while the new content is being parsed:
// Retain previous content during updates (avoids showing loading state)
val markdownState = rememberMarkdownState(
markdown,
retainState = true
)
Markdown(markdownState)
// With dynamic content loading
val markdownState = rememberMarkdownState(
key, // key that triggers re-parsing
retainState = true
) {
"# Dynamic content $counter"
}
Markdown(markdownState)
This is particularly useful when content updates frequently or when you want to avoid flickering between the old content and the loading state.
Since version 0.33.0, the library supports rendering large markdown documents efficiently using
LazyColumn instead of Column. This is particularly useful for very long markdown content.
Markdown(
markdownState = markdownState,
success = { state, components, modifier ->
LazyMarkdownSuccess(state, components, modifier, contentPadding = PaddingValues(16.dp))
},
modifier = Modifier.fillMaxSize()
)
[!NOTE]
This approach is also advised if you want to retain scroll position even when navigating away See: https://github.com/mikepenz/multiplatform-markdown-renderer/issues/374 Retaining state in the VM ensures parsing will not have to be done again, and the component can be immediately filled.
// In the VM setup the flow to parse the markdown
val markdownFlow = parseMarkdownFlow("# Markdown")
.stateIn(lifecycleScope, SharingStarted.Eagerly, State.Loading())
// In the Composable use the flow
val state by markdownFlow.collectAsStateWithLifecycle()
Markdown(state)
If you want to pre-parse content before showing the UI and hand the result to Markdown without any
Flow/StateFlow machinery, use parseMarkdown. It parses on the calling thread and returns the final,
immutable State directly (State.Success on success, or State.Error on failure).
// Parse ahead of time and pass the already-parsed state to the Composable
val state = parseMarkdown("# Markdown")
Markdown(state)
[!NOTE]
Parsing happens on the calling thread. For large documents consider invoking this off the main thread.
The library offers the ability to modify different behaviour when rendering the markdown.
Markdown(
content,
colors = markdownColor(text = Color.Red),
typography = markdownTypography(h1 = MaterialTheme.typography.body1)
)
By default, the MarkdownText animates size changes (if images are loaded).
Markdown(
content,
animations = markdownAnimations(
animateTextSize = {
this
/** No animation */
}
),
)
Starting with 0.16.0 the library includes support for extended-spans.
The library was integrated to make it multiplatform-compatible. All credits for its functionality go to Saket Narayan.
It is not enabled by default, however you can enable it quickly by configuring the extendedSpans
for your Markdown composeable.
Define the ExtendedSpans you want to apply (including optionally your own custom ones) and return
it.
Markdown(
content,
extendedSpans = markdownExtendedSpans {
val animator = rememberSquigglyUnderlineAnimator()
remember {
ExtendedSpans(
RoundedCornerSpanPainter(),
SquigglyUnderlineSpanPainter(animator = animator)
)
}
}
)
The library already handles a significant amount of different tokens, however not all. To allow
special integrations expand this, you can pass in a custom annotator to the Markdown
composeable. This annotator allows you to customize existing handled tokens, but also add new
ones.
Markdown(
content,
annotator = markdownAnnotator { content, child ->
if (child.type == GFMElementTypes.STRIKETHROUGH) {
append("Replaced you :)")
true // return true to consume this ASTNode child
} else false
}
)
// Use the bullet list symbol from the original markdown
CompositionLocalProvider(LocalBulletListHandler provides { type, bullet, index, listNumber, depth -> "$bullet " }) {
Markdown(content)
}
// Replace the ordered list symbol with `A.)` instead.
CompositionLocalProvider(LocalOrderedListHandler provides { type, bullet, index, listNumber, depth -> "A.) " }) {
Markdown(content, Modifier.fillMaxSize().padding(16.dp).verticalScroll(scrollState))
}
Since v0.9.0 it is possible to provide custom components, instead of the default ones.
This can be done by providing the components MarkdownComponents to the Markdown composable.
Use the markdownComponents() to keep defaults for non overwritten components.
The MarkdownComponent will expose access to
the content: String, node: ASTNode, typography: MarkdownTypography,
offering full flexibility.
// Simple adjusted paragraph with different Modifier.
val customParagraphComponent: MarkdownComponent = {
Box(modifier = Modifier.fillMaxWidth()) {
MarkdownParagraph(it.content, it.node, Modifier.align(Alignment.CenterEnd))
}
}
// Full custom paragraph example
val customParagraphComponentComplex: MarkdownComponent = {
// build a styled paragraph. (util function provided by the library)
val styledText = buildAnnotatedString {
pushStyle(LocalMarkdownTypography.current.paragraph.toSpanStyle())
buildMarkdownAnnotatedString(it.content, it.node, annotatorSettings())
pop()
}
// define the `Text` composable
Text(
styledText,
textAlign = TextAlign.End
)
}
// Define the `Markdown` composable and pass in the custom paragraph component
Markdown(
content,
components = markdownComponents(
paragraph = customParagraphComponent // customParagraphComponentComplex
)
)
Another example to of a custom component is changing the rendering of an unordered list.
// Define a custom component for rendering unordered list items in Markdown
val customUnorderedListComponent: MarkdownComponent = {
// Use the MarkdownListItems composable to render the list items
MarkdownListItems(it.content, it.node, depth = 0) { startNumber, index, child ->
// Render an icon for the bullet point with a green tint
Icon(
imageVector = icon,
tint = Color.Green,
contentDescription = null,
modifier = Modifier.size(20.dp),
)
}
}
// Define the `Markdown` composable and pass in the custom unorderedList component
Markdown(
content,
components = markdownComponents(
unorderedList = customUnorderedListComponent
)
)
Starting with 0.30.0, the library includes support for rendering tables in markdown. The Markdown
composable will automatically handle table elements in your markdown content.
val markdown = """
| Header 1 | Header 2 |
|----------|----------|
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |
""".trimIndent()
Markdown(markdown)
The library renders GitHub alerts — NOTE,
TIP, IMPORTANT, WARNING and CAUTION — as an accent bar with an icon and a title.
val markdown = """
> [!NOTE]
> Useful information that users should know, even when skimming content.
""".trimIndent()
Markdown(markdown)
The accent colors, dimensions and paddings are grouped into dedicated models, the title style is
exposed via markdownTypography(alertTitle = ...):
Markdown(
markdown,
colors = markdownColor(alert = markdownAlertColors(note = Color.Blue)),
dimens = markdownDimens(alert = markdownAlertDimens(barThickness = 2.dp)),
padding = markdownPadding(alert = markdownAlertPadding(iconSpacing = 12.dp)),
)
The icons are swappable via LocalMarkdownAlertIcons:
CompositionLocalProvider(
LocalMarkdownAlertIcons provides markdownAlertIcons(note = Icons.Outlined.Info)
) {
Markdown(markdown)
}
To fully replace the rendering, override the alert component through markdownComponents().
Surfaced from shared tags and platforms — no rankings paid for.