Docs / Component overrides / Component overrides

Component overrides

How to replace any built-in Scrollup component with your own version using the overrides.ts re-export file.

Scrollup lets you replace any core layout component — Sidebar, Topbar, Footer, and more — without forking the codebase. The override system is a single file you edit directly.

How it works

Every layout (DocsLayout, SplashLayout) imports its components from src/lib/overrides.ts instead of directly from src/components/. To swap a component, you change the import source for that export in overrides.ts.

export { default as Sidebar } from '@/components/Sidebar.astro';   // default
// export { default as Sidebar } from '../components/MySidebar.astro'; // override

Because the re-export is static, Rollup can statically analyze it and tree-shake correctly — this is why Scrollup uses this pattern instead of a config-driven string path (which Astro’s static build can’t analyze).

Warning

Your replacement component must accept the same props as the original. If props change between Scrollup versions, you’ll need to update your override accordingly.

Overrideable components

Export	Default file	Typical reason to override
`Sidebar`	`Sidebar.astro`	Custom navigation, external link groups
`Topbar`	`Topbar.astro`	Extra nav items, custom logo placement
`Footer`	`Footer.astro`	Additional links, legal text, newsletter
`TableOfContents`	`TableOfContents.astro`	Different heading levels or styling
`PageLinks`	`PageLinks.astro`	Prev/next link styling
`Breadcrumbs`	`Breadcrumbs.astro`	Custom breadcrumb logic

Create your replacement component

Copy the original as a starting point:

cp src/components/Footer.astro src/components/MyFooter.astro

Update overrides.ts

Edit src/lib/overrides.ts to point at your version:

// Before:
export { default as Footer } from '@/components/Footer.astro';
// After:
export { default as Footer } from '../components/MyFooter.astro';

Start the dev server

Run npm run dev — your footer is now used everywhere.

File layout

src/
- lib/
  - overrides.ts ← edit this file to override components
- components/
  - Sidebar.astro
  - Topbar.astro
  - Footer.astro
  - MyFooter.astro ← your custom component lives here
- layouts/
  - DocsLayout.astro ← imports from overrides.ts
  - SplashLayout.astro ← imports from overrides.ts

What is NOT overrideable via this system

src/pages/index.astro (landing page) — edit directly
src/pages/404.astro — edit directly
MDX components in src/components/mdx/ — pass custom components via the components prop in MDX frontmatter, or add to src/components/mdx/index.ts

Tip

The src/pages/ files intentionally import directly rather than going through overrides.ts. They are special-purpose pages, not part of the docs layout hierarchy.

Last updated: April 6, 2026

Edit this page on GitHub

← Previous

Self-Hosted

Plugin system overview