> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# 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`:

```ts title="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:

```ts title="rspress.config.ts"
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:

```tsx title="compUi.tsx"
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:

```tsx title="compSideEffect.tsx"
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:

```mdx title="foo.mdx"
---
pageType: custom
---
```

For component routes, export `frontmatter` to specify `pageType`:

```tsx title="foo.tsx"
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:

```mdx title="foo.mdx"
---
navbar: false
sidebar: false
outline: false
footer: false
globalUIComponents: false
---
```