Rspress Custom Theme

Guide for customizing Rspress (v2) themes. Rspress offers four levels of customization, from lightest to heaviest. Always prefer the lightest approach that meets the requirement — lighter approaches are more maintainable and survive Rspress upgrades.

Workflow

Understand the user's goal — what do they want to change? (colors, layout, inject content, replace a component entirely?)
Pick the right level using the decision flow below
Set up
theme/index.tsx
if needed (Levels 1A, 3, 4 all need it)
Implement following the patterns in this skill and reference files
Verify the user's Rspress version is v2 (imports use
```
@rspress/core/*
```
not
```
rspress/*
```
)

Decision Flow

User wants to...	Level	Approach
Change brand colors, fonts, spacing, shadows	1	CSS variables
Adjust a specific component's style (borders, padding, etc.)	2	BEM class overrides
Add content around existing components (banners, footers, logos)	3	Layout slots (wrap)
Override MDX rendering (custom `<h1>` , `<code>` , etc.)	3	`components` slot
Wrap the app in a provider (state, analytics, auth)	4	Eject `Root`
Replace built-in icons (logo, GitHub, search, etc.)	—	Icon re-export
Completely replace a built-in component	4	Eject that component
Add a global floating component (back-to-top, chat widget)	—	`globalUIComponents` config
Control page layout structure (hide sidebar, blank page)	—	Frontmatter `pageType`

theme/index.tsx — The Entry Point

Levels 1A, 3, and 4 all require a

theme/index.tsx

file in the project root (sibling to

docs/

). This is the single entry point for all theme customizations:

text

project/
├── docs/
├── theme/
│   ├── index.tsx        # Theme entry — re-exports + overrides
│   ├── index.css         # CSS variable / BEM overrides (optional)
│   └── components/       # Ejected components (Level 4)
└── rspress.config.ts

Minimal setup:

tsx

// theme/index.tsx
import './index.css'; // optional
export * from '@rspress/core/theme-original';

Critical import rule: Inside

theme/

files, always import from

@rspress/core/theme-original

. The path

@rspress/core/theme

resolves to your own

theme/index.tsx

, which causes circular imports. (In

docs/

MDX files,

@rspress/core/theme

is fine — it correctly points to your custom theme.)

Level 1: CSS Variables

Override CSS custom properties for brand colors, backgrounds, text, code blocks, and more.

Option A —

theme/index.css

(use when you also have component overrides in

theme/index.tsx

css

/* theme/index.css */
:root {
  --rp-c-brand: #7c3aed;
  --rp-c-brand-light: #8b5cf6;
  --rp-c-brand-dark: #6d28d9;
}
.dark {
  --rp-c-brand: #a78bfa;
}

Option B —

globalStyles

(use when you only need CSS changes, no component overrides):

// rspress.config.ts
export default defineConfig({
  globalStyles: path.join(__dirname, 'styles/custom.css'),
});

Full variable list: Read
references/css-variables.md
for all available CSS variables with light/dark defaults.

Level 2: BEM Class Overrides

All built-in components follow BEM naming:

.rp-[component]__[element]--[modifier]

Common targets:

.rp-nav

.rp-link

.rp-tabs

.rp-codeblock

.rp-codeblock__title

.rp-nav-menu__item--active

Use these in your CSS file for targeted style changes when CSS variables aren't granular enough.

Level 3: Wrap (Layout Slots)

Inject content at specific positions in the layout without replacing built-in components. Override

Layout

theme/index.tsx

tsx

// theme/index.tsx
import { Layout as OriginalLayout } from '@rspress/core/theme-original';
export * from '@rspress/core/theme-original';

export function Layout() {
  return (
    <OriginalLayout beforeNavTitle={<MyLogo />} bottom={<CustomFooter />} />
  );
}

Use runtime hooks inside slot components — import from

@rspress/core/runtime

useDark()

useLang()

useVersion()

usePage()

useSite()

useFrontmatter()

useI18n()

All slots & examples: Read
references/layout-slots.md
for the complete slot list and usage patterns including i18n and MDX component overrides.

Level 4: Eject

Copy a built-in component's source for full replacement. Only use when wrap/slots cannot achieve the customization.

bash

rspress eject           # list available components
rspress eject DocFooter # eject to theme/components/DocFooter/

Then re-export in

theme/index.tsx

(named export takes precedence over the wildcard):

tsx

export * from '@rspress/core/theme-original';
export { DocFooter } from './components/DocFooter';

Component list & patterns: Read
references/eject-components.md
for available components, workflow, and common patterns.

Custom Icons

Rspress has 27 built-in icons used across the UI. You can replace any of them by re-exporting your own icon component with the same name — no ejection needed. This uses the same

theme/index.tsx

mechanism: your named export takes precedence over the wildcard re-export.

Icon type: Each icon is a React component or a URL string:

import type { FC, SVGProps } from 'react';
type Icon = FC<SVGProps<SVGSVGElement>> | string;

Example 1 — Replace an icon with a custom SVG component:

tsx

// theme/index.tsx
export * from '@rspress/core/theme-original';

// Named export overrides the wildcard — replaces the GitHub icon site-wide
export const IconGithub = (props: React.SVGProps<SVGSVGElement>) => (
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}>
    <path d="M12 2C6.477 2 2 6.484 2 12.017c0 ..." fill="currentColor" />
  </svg>
);

Example 2 — Use an SVGR import:

tsx

// theme/index.tsx
export * from '@rspress/core/theme-original';

import CustomGithubIcon from './icons/github.svg?react';
export const IconGithub = CustomGithubIcon;

Using
SvgWrapper
in MDX or custom components:

mdx

import { SvgWrapper, IconGithub } from '@rspress/core/theme';

<SvgWrapper icon={IconGithub} width={24} height={24} />

Available icons:

IconArrowDown

IconArrowRight

IconClose

IconCopy

IconDeprecated

IconDown

IconEdit

IconEmpty

IconExperimental

IconExternalLink

IconFile

IconGithub

IconGitlab

IconHeader

IconJump

IconLink

IconLoading

IconMenu

IconMoon

IconScrollToTop

IconSearch

IconSmallMenu

IconSuccess

IconSun

IconTitle

IconWrap

IconWrapped

Source: See the icons source for default implementations.

Global UI Components

For components that should render on every page without theme overrides:

// rspress.config.ts
export default defineConfig({
  globalUIComponents: [
    path.join(__dirname, 'components', 'BackToTop.tsx'),
    [
      path.join(__dirname, 'components', 'Analytics.tsx'),
      { trackingId: '...' },
    ],
  ],
});

Page Types

Control layout per page via frontmatter

pageType

Value	Description
`home`	Home page with navbar
`doc`	Standard doc with sidebar and outline
`doc-wide`	Doc without sidebar/outline
`custom`	Custom content with navbar only
`blank`	Custom content without navbar
`404`	404 error page

Fine-grained: set

navbar: false

sidebar: false

outline: false

footer: false

individually.

Common Pitfalls

Circular import: Using
```
@rspress/core/theme
```
instead of
```
@rspress/core/theme-original
```
in
```
theme/
```
files — causes infinite loop.
Eject over-use: Ejecting when a Layout slot or CSS variable would suffice — creates upgrade burden.
Missing re-export: Forgetting
```
export * from '@rspress/core/theme-original'
```
in
```
theme/index.tsx
```
— breaks all un-overridden components.

v1 imports: Using

rspress/theme

@rspress/theme-default

— these are v1 paths. v2 uses

@rspress/core/theme-original

Reference

Custom theme guide: https://rspress.rs/guide/basic/custom-theme
CSS variables: https://rspress.rs/ui/vars
Layout component: https://rspress.rs/ui/layout-components/layout
Built-in icons: https://rspress.rs/ui/icons/
Built-in hooks: https://rspress.rs/ui/hooks/
CLI commands (eject): https://rspress.rs/api/commands

rspress-custom-theme

NPX Install

Tags

SKILL.md Content