title-header
The header is one of the most flexible parts of Stardrive. It can be a sticky bar, an overlay that morphs on scroll, a minimal close button, or disappear entirely. This guide walks through where each option is set and how the pieces fit together.
Where the header is configured
Header options flow through three layers, from the page down to the component that actually renders the bar:
1. Page
Pass a header prop
Each page hands a header object to the Layout. This is where you override behaviour per route.
2. Layout
default.astro / article.astro
The Layout reads the page's header prop, merges it with its own hardcoded defaults, and forwards the result to the Header component.
3. Component
header.astro
The component receives the final props and renders one of four variants based on the combination.
Two levels of defaults
There is no header key in theme.config.ts. Defaults are coded in two places - both are plain code, so you edit them directly.
Layout default
In ./src/layouts/default.astro (and article.astro), some values are hardcoded and passed to every page that uses the Layout. These are the things you almost never want to change per page:
github- the GitHub link shown on the right (currently points at the Stardrive repo).ctaButton- the call-to-action button (defaults to the "Sign up" label and the signup route).isHome- forwarded from the Layout so the logo is not linked on the homepage.
Edit these directly in the Layout file to change them globally.
Component default
In ./src/components/layout/header.astro, the variant is chosen from the combination of fixed, overlay, and closeIcon. When none of those are set, the component falls back to the CSS-fixed variant - a header that sticks to the top while scrolling and hides once the footer covers most of the viewport. That fallback lives in the component's own logic, not in a config file.
Change a default once, apply everywhere
Because the defaults live in code, a single edit in the Layout (for github / ctaButton) or the component (for the fallback variant) propagates to every page. You only need the per-page header prop when a route should behave differently.
Overriding on the page
Pass a header object to the Layout to override the defaults for a single page. Only the keys you set are applied - everything else falls back to the Layout and component defaults.
---import Layout from "@layouts/default.astro";
<Layout title="My page" header={{ overlay: true, // start as an overlay over the hero scrollDownThreshold: 600, // switch to the fixed bar after 600px showTopBanner: false, // hide the top promo banner on this page }}> <section class="hero">…</section> <section class="content">…</section></Layout>---Back button instead of logo
Set button to replace the logo with a "back" link - ideal for detail pages.
Hide the header entirely
Set hidden: true when a page should not show a header at all (e.g. a landing page).
---<Layout title="Article" header={{ button: { text: "Back to blog", href: "/blog" }, fixed: true, }}> …</Layout>------<Layout title="Landing page" header={{ hidden: true }}> …</Layout>---All header options
These are the props accepted by the header object on the Layout. The Layout forwards the relevant subset to the Header component; a few additional props (github, ctaButton, overlayTheme) are only set at the Layout or component level.
| Prop | Type | Default | What it does |
|---|---|---|---|
hidden | boolean | undefined | When true, the header is not rendered at all. Use for full-bleed landing pages. |
fixed | boolean | undefined | Renders a full-width bar pinned to the very top that does not move on scroll. Mutually exclusive with overlay and closeIcon. |
overlay | boolean | undefined | Starts the header as an absolute overlay (typically over a hero), then transitions to a fixed bar once scrollDownThreshold is passed. Mutually exclusive with fixed. |
scrollDownThreshold | number | header out of viewport | Only used with overlay. Pixels scrolled before the overlay morphs into the fixed bar. Should be larger than the header height for a clean transition. |
closeIcon | boolean | undefined | Replaces the logo/button with a close icon that links back to the home page. Used on the 404 page. Mutually exclusive with fixed and overlay. |
button | { text, href } | logo | Shows a "back" button (with an arrow icon) instead of the site logo. Common on list and detail pages (e.g. "Back to blog"). |
showTopBanner | boolean | from theme.config.ts | Force-hides (false) or force-shows (true) the top promo banner for this page, overriding the global topBanner setting. |
Layout-only props
A few props are not exposed on the page-level header object because they are project-wide: github (the repo link), ctaButton (the right-hand CTA), and overlayTheme (force light/dark for overlay headers). Edit them directly in ./src/layouts/default.astro or ./src/components/layout/header.astro.
Common combinations
The variant is picked from the combination of fixed, overlay, and closeIcon. These three are mutually exclusive - set at most one.
| Combination | Result | Typical use |
|---|---|---|
| (none set) | CSS-fixed header that sticks to the top and hides when the footer covers the viewport. | Most content pages. |
fixed: true | Full-width bar pinned to the very top, never moves. | List pages with a back button (blog categories, tags). |
overlay: true + scrollDownThreshold | Overlay over the hero, then morphs into a fixed bar after the threshold. | Homepage and hero-driven pages. |
closeIcon: true | Just a close icon linking home. | Error pages (e.g. 404). |
button + fixed: true | Pinned bar with a back button instead of the logo. | Sub-listings where the user came from an overview. |
hidden: true | No header at all. | Standalone landing or splash pages. |
showTopBanner: false | Any variant, but the top promo banner is hidden. | Legal/privacy pages where you want a calmer chrome. |
Mutually exclusive variants
fixed, overlay, and closeIcon select different rendering branches in the component. Setting more than one produces undefined behaviour - the component checks closeIcon first, then fixed, then overlay, so only one ever applies. Pick the one that matches your intent.
Ready for the everyday work?
Learn how content flows through Stardrive: blog, FAQ, integrations, and events.
