Installation overview

Set up Prose UI in your React + MDX project.

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

If you're using Next.js or TanStack Start, follow the framework guides for Next.js or TanStack Start to get tailored instructions.

General overview

Prose UI has three main pieces:

React components
These components power callouts, code blocks, steps, and other rich elements in your MDX content.
Available as mdxComponents from @prose-ui/react for any React runtime, and @prose-ui/next for Next.js.
CSS styles
Provides typography and styling for both prose and components.
Available as prose-ui.css from @prose-ui/style. Wrap your content with the prose-ui CSS class.
Remark plugins
Enables code highlighting, math formulas, and other transformations during the Markdown/MDX build step.
remarkPlugins() is available from @prose-ui/core. Add these plugins to your Markdown/MDX pipeline.

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

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'

CSS styles

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

Import prose-ui.css into your global stylesheet and wrap your content in a container with the prose-ui class:

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

<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.

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.