Prose UI

Installation overview

Prose UI works with any React + MDX setup.
This page gives you a high‑level overview and generic installation steps.

If you’re using a specific framework like Next.js or TanStack Start, you’ll get a smoother experience by following the corresponding framework guide instead.

General overview

Prose UI has three main pieces:

  • React components
    Available as @prose-ui/react for any React runtime, and @prose-ui/next for Next.js.
    You only need one of these packages, and you pass its components into your MDX renderer.

  • CSS styles
    Available from @prose-ui/style.
    You import a single CSS file into your global styles and wrap your content in a prose-ui container.

  • Remark plugins
    Available from @prose-ui/core.
    You add these plugins to your Markdown/MDX pipeline to enable code highlighting, math, images, and other components.

The rest of this page walks through each of these pieces in a generic React + MDX setup.

  1. React components

    To get highlighted code blocks, callouts, math, and other components, you need to provide Prose UI components to your MDX renderer.

    For any React app:

    import { mdxComponents } from '@prose-ui/react'

    For Next.js apps:

    // Uses next/link and next/image internally
import { mdxComponents } from '@prose-ui/next'

    Then pass mdxComponents to your MDX renderer. For example, with Content Collections:

    import { MDXContent } from '@content-collections/mdx/react'
import { mdxComponents } from '@prose-ui/react'

<MDXContent code={markdownContent} components={mdxComponents} />
    You can also import individual components
    import {
  Callout,
  CodeBlock,
  Frame,
  Heading,
  Image,
  Link,
  InlineMath,
  BlockMath,
  // ...
} from '@prose-ui/react'

  2. CSS styles

    Prose UI ships default typography and component styles in a single stylesheet, scoped under the prose-ui class.

    Import the styles into your global stylesheet:

    globals.css
    @import '@prose-ui/style/prose-ui.css';
@import '@prose-ui/style/katex.min.css';
    • prose-ui.css – base typography and component styles
    • katex.min.css – only needed if you use math formulas

    Then wrap your rendered Markdown/MDX content in a prose-ui container:

    <div className="prose-ui">
  {/* Your rendered Markdown content */}
</div>

    Prose UI uses the dark class on the <html> element to switch to dark mode, so it plugs into most existing theme toggles.

    Customizing styles

    The easiest way to customize Prose UI is by overriding the CSS variables defined in @prose-ui/style/prose-ui.css. You can inspect the generated CSS and override the variables in your own stylesheet.

  3. Remark plugins

    The remarkPlugins(options) function from @prose-ui/core powers most of the “magic”:

    • Syntax‑highlighted code blocks
    • LaTeX math formulas
    • Mapping basic Markdown to React components (e.g. images to <Image>)

    You should initialize the plugins once and pass them into your Markdown/MDX pipeline.

    For example, with Content Collections:

    import { remarkPlugins } from '@prose-ui/core'

const plugins = remarkPlugins({
  // Optional config
  image: {
    imageDir: './public',
  },
})

const content = await compileMDX(ctx, post, {
  remarkPlugins: plugins,
})

    In other setups (e.g. your own MDX bundler, Vite plugin, or a custom build step), you wire plugins into the place where you normally configure remarkPlugins. The exact API will differ, but the idea stays the same: create the plugins with remarkPlugins() and pass them to your MDX processor.

Created by Valdemaras, designed by Domas. Source code available on GitHub.