Rspress Custom Theme

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

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

Decision flow

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:

textCopy code
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:

tsxCopy code
// 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):

cssCopy code
/* 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):

tsCopy code
// 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 in theme/index.tsx:

tsxCopy code
// 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.

bashCopy code
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):

tsxCopy code
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:

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

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

tsxCopy code
// 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:

tsxCopy code
// 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:

mdxCopy code
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:

tsCopy code
// 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:

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 or @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