#Customizing page

Rspress provides several ways to customize page content:

• Adding custom global components.
• Adding custom global styles.
• Customizing page layout structure.

#Custom global components

In some scenarios, you may need custom global components on every page. Use the globalUIComponents option for this.

#How to use

Add the following configuration in rspress.config.ts:

import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});

Each globalUIComponents item can be either a component file path string or a tuple. In the tuple form, the first item is the component file path and the second item is the component props. For example:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  globalUIComponents: [
    [
      path.join(__dirname, 'components', 'MyComponent.tsx'),
      {
        foo: 'bar',
      },
    ],
  ],
});

When you register global components, Rspress automatically renders these React components in the theme without requiring manual imports.

Global components can implement many custom features, such as:

import React from 'react';

// Need a default export
// Props come from your config
export default function PluginUI(props?: { foo: string }) {
  return <div>This is a global layout component</div>;
}

The component content is then rendered in the theme, for example to add a BackToTop button.

You can also use a global component to register side effects:

import { useEffect } from 'react';
import { useLocation } from '@rspress/core/runtime';

// Need a default export
export default function PluginSideEffect() {
  const { pathname } = useLocation();
  useEffect(() => {
    // Executed when the component renders for the first time
  }, []);

  useEffect(() => {
    // Executed when the route changes
  }, [pathname]);
  return null;
}

The component side effects then run in the theme. For example, side effects are useful for:

• Redirecting specific page routes.
• Binding click events on page img tags to implement image zoom.
• Reporting page view data when the route changes.

#Custom layout structure

Rspress provides pageType for customizing page layout.

#Using pageType

Rspress convention-based routing supports two route types: document routes, written with .md(x) files, and component routes, written with .jsx or .tsx files.

For document routes, add the pageType field in frontmatter to specify the page layout:

---
pageType: custom
---

For component routes, export frontmatter to specify pageType:

export const frontmatter = {
  // Declare layout type
  pageType: 'custom',
};

pageType supports the following values:

• home: Homepage, including the top navbar and homepage layout content.
• doc: Doc page, including the top navbar, left sidebar, body content, and right-side outline.
• doc-wide: Wide doc page, where the main content can occupy a wider area when outline: false and sidebar: false are used together.
• custom: Custom page, including the top navbar and custom content.
• blank: Also a custom page, but without the top navbar.
• 404: Not found page.

#Using fine-grained switches

In addition to page-level pageType configuration, Rspress provides fine-grained frontmatter switches:

• navbar: Whether to display the top navbar. Set it to false to hide the navbar.
• sidebar: Whether to display the sidebar. Set it to false to hide the sidebar.
• outline: Whether to display the outline. Set it to false to hide the outline.
• footer: Whether to display the footer. Set it to false to hide the footer.
• globalComponents: Whether to display global components. Set it to false to hide global components.

Example:

---
navbar: false
sidebar: false
outline: false
footer: false
globalUIComponents: false
---