---
title: "Markdown"
description: "Renders a message written in chat markdown — formatting, mentions, timestamps, spoilers, code blocks — with the library's own parts."
---

`Markdown` takes a message as a string and renders it the way a Discord-inspired
chat client does: `**bold**`, `*italic*`, `__underline__`, `~~strike~~`,
`||spoilers||`, inline and fenced code, `#`/`##`/`###` headings, `-#` subtext,
lists, `>` and `>>>` quotes, links, and the angle-bracket tokens — `<@id>`,
`<@&id>`, `<#id>`, `</command:id>`, `<:emoji:id>` and `<t:1700000000:R>`.

Line breaks follow the client too. Every newline is a line break and a blank
line stays an empty line, before and after a list as well as between
paragraphs; `_ _` is an empty line written on purpose. A list item indented
under another one nests, with a circle bullet and then a square one.

Each piece renders through a part you already have: mentions are `Mention`,
code is `InlineCode` and `CodeBlock`, spoilers are `Spoiler`, timestamps are
`Timestamp`, server emoji are `CustomEmoji`. A general Markdown library would
give you HTML; this gives you the same components as the rest of the feed.
For HTML a general renderer already produced — docs, articles, a CMS field —
use [Typeset](/docs/components/typeset) instead.

The source is parsed into a tree and rendered as components. It is never
injected as HTML, and only `http` and `https` addresses become links.

_Live example of Markdown — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add markdown
``` Registry dependencies, installed with it: button, code-block, custom-emoji, inline-code, mention, modal, spoiler, timestamp.

Files written — React: components/ui/markdown.tsx, components/ui/markdown-syntax.ts. Vue: components/ui/markdown/Markdown.vue, components/ui/markdown/MarkdownBlocks.vue, components/ui/markdown/MarkdownInline.vue, components/ui/markdown/markdown-syntax.ts, components/ui/markdown/index.ts.

## Usage

React:

```tsx
import { Markdown } from "@/components/ui/markdown"
```

Vue:

```ts
import { Markdown, MarkdownBlocks, MarkdownInline } from "@/components/ui/markdown"
```

Mentions, roles and channels arrive as ids. Pass `resolveMention` to turn an
id into a name (and a role colour, or a user avatar); an id it does not know
renders as `unknown-user`, `unknown-role` or `unknown-channel`. A token that
carries a name instead of an id, such as `<@username>`, renders as written.

Server emoji render as their `:name:` text until you pass `resolveEmoji`,
which returns the image URL for an emoji's id. newt/ui never fetches an image
on its own. A message made only of emoji renders them large.

The parser is exported too, from `markdown-syntax.ts`, for code that needs the
tree without rendering it — a search index, a plain-text preview:

```ts
import { parseMarkdown } from "@/components/ui/markdown-syntax"

parseMarkdown("**hi** <@1001>")
// [{ type: "paragraph", children: [{ type: "strong", … }, …] }]
```

## API reference

**`Markdown`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `string` | — | The message source, in chat markdown. |
| `resolveMention` | `(kind, id) => MarkdownMentionTarget \| undefined` | — | `kind` is user, role or channel; returns `{ name, color?, avatar? }`: name, role colour and avatar for a mention id. Unknown numeric ids show the unknown label; names show as written. |
| `resolveEmoji` | `(emoji) => string \| undefined` | — | `emoji` is `{ id, name, animated }`. Returns the image URL for a server emoji. Without it the emoji shows as :name: text. |
| `onMentionClick / @mention-click` | `(mention: { kind; id }) => void` | — | Makes mentions buttons. In Vue, also set `interactiveMentions`. Without it they are read-only text, out of the tab order. |
| `headingOffset` | `number` | `2` | Added to a heading's level to pick its element, so # renders an <h3> and a message never outranks the page. |
| `locale` | `string` | — | Locale for timestamps. Defaults to the reader's. |
| `linkWarning` | `boolean` | `true` | Ask before opening a masked link ([text](/docs/components/url)), whose text hides its address. |
| `labels` | `Partial<MarkdownLabels>` | — | Translations for the words the renderer writes itself: the unknown-mention labels, the link warning and the accessible name of a hidden spoiler (`spoiler`). |

The registry exports `Markdown`, `defaultMarkdownLabels` and, from
`markdown-syntax`, `parseMarkdown`, `parseInline` and `isEmojiOnly`.

## Accessibility

Headings start two levels down by default, so a `#` inside a message is an
`<h3>` under the page's own headings; change `headingOffset` to fit your
outline. Read-only mentions are text rather than buttons, so a feed of
messages does not add a tab stop per mention. A masked link opens a dialog
that shows the full address before leaving the page. The dialog takes focus
when it opens, keeps Tab inside it, closes on Escape and hands focus back to
the link. A hidden spoiler is announced by its `spoiler` label rather than by
what it hides. Translate every label through `labels` when the page is not in
English.

[Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Markdown reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
