# Eject Components Reference

Eject copies a built-in component's source code into your project for full customization. This is the heaviest approach — ejected components do not receive automatic updates when Rspress upgrades. Prefer CSS variables, BEM overrides, or Layout slots whenever possible.

Official reference: <https://rspress.rs/api/commands>

---

## Eject Command

```bash
# List all available components
rspress eject

# Eject a specific component
rspress eject <ComponentName>
```

Ejected source is placed in `theme/components/<ComponentName>/`.

## Available Components

| Component        | Description                               | Consider wrapping first?                         |
| ---------------- | ----------------------------------------- | ------------------------------------------------ |
| `Layout`         | Main layout container with all slot props | Yes — use Layout slots instead                   |
| `Root`           | Application root wrapper                  | Only eject for global providers                  |
| `Banner`         | Notification banner at top of page        | Check `top` slot first                           |
| `NavTitle`       | Navigation logo and title                 | Check `navTitle` / `beforeNavTitle` slots        |
| `HomeLayout`     | Complete home page layout                 | Check home page slots first                      |
| `HomeHero`       | Hero section on home page                 | Check `beforeHero` / `afterHero` slots           |
| `HomeFeature`    | Feature grid cards                        | Check `beforeFeatures` / `afterFeatures` slots   |
| `HomeBackground` | Home page background effects              | Try CSS variables first                          |
| `HomeFooter`     | Home page footer                          | Check `bottom` slot first                        |
| `DocFooter`      | Documentation page footer                 | Check `beforeDocFooter` / `afterDocFooter` slots |
| `EditLink`       | "Edit this page" link                     | Configure via `themeConfig.editLink`             |
| `LastUpdated`    | Last updated timestamp                    | Usually config is enough                         |
| `PrevNextPage`   | Previous/next page navigation             | Check `beforeDocFooter` slot                     |
| `OverviewGroup`  | Overview page group cards                 | —                                                |
| `Tag`            | Tag/label component                       | —                                                |

## Step-by-Step Eject Workflow

1. **Eject the component:**

   ```bash
   rspress eject DocFooter
   ```

2. **Re-export in theme/index.tsx:**

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

   The named export takes precedence over the wildcard re-export, so Rspress uses your custom version.

3. **Modify the ejected source** in `theme/components/DocFooter/`.

## Common Pattern: Root for Global Providers

The most common eject use case is wrapping the entire app in a context provider (state management, analytics, auth, etc.):

```tsx
// theme/components/Root/index.tsx
import type { RootProps } from '@rspress/core/theme';

export function Root({ children }: RootProps) {
  return (
    <ThemeProvider>
      <AnalyticsProvider>{children}</AnalyticsProvider>
    </ThemeProvider>
  );
}
```

```tsx
// theme/index.tsx
export * from '@rspress/core/theme-original';
export { Root } from './components/Root';
```

## Common Pattern: Custom Home Page (HomeLayout)

When the default home page structure (Hero + Features) doesn't meet the design requirements — for example, you need a completely different landing page with custom sections, animations, or a non-standard layout — write a custom `HomeLayout` component and re-export it directly:

```tsx
// theme/components/HomeLayout/index.tsx
import { useSite, useLang } from '@rspress/core/runtime';

export function HomeLayout() {
  const site = useSite();
  const lang = useLang();
  const { title, description } = site.siteData;

  return (
    <div className="custom-home">
      <section className="hero">
        <h1>{title}</h1>
        <p>{description}</p>
        <div className="hero-actions">
          <a
            href={lang === 'zh' ? '/zh/guide/start' : '/guide/start'}
            className="primary-btn"
          >
            Get Started
          </a>
          <a href="https://github.com/..." className="secondary-btn">
            GitHub
          </a>
        </div>
      </section>

      <section className="showcase">
        {/* Custom content: testimonials, stats, demos, etc. */}
      </section>
    </div>
  );
}
```

```tsx
// theme/index.tsx
export * from '@rspress/core/theme-original';
export { HomeLayout } from './components/HomeLayout';
```

The named export overrides the built-in `HomeLayout` from the wildcard re-export — no need to eject first.

If you only need to add content before/after the Hero or Features sections (without replacing the entire home page), prefer Layout slots (`beforeHero`, `afterHero`, `beforeFeatures`, `afterFeatures`) instead — see `references/layout-slots.md`.

## Common Pattern: Custom Doc Footer

```tsx
// theme/components/DocFooter/index.tsx
import { useFrontmatter } from '@rspress/core/runtime';

export function DocFooter() {
  const frontmatter = useFrontmatter();
  return (
    <footer className="custom-doc-footer">
      {frontmatter.author && <span>Author: {frontmatter.author}</span>}
      <a href="https://github.com/...">Edit this page</a>
    </footer>
  );
}
```

## Important Notes

- Always import from `@rspress/core/theme-original` in `theme/` files, never from `@rspress/core/theme` (the latter resolves to your own `theme/index.tsx`, causing circular imports).
- After ejecting, you own that component. Track Rspress changelogs for upstream changes you might want to incorporate manually.
- Run `rspress eject` (no args) to see the up-to-date list of available components — the list above may change between Rspress versions.