@sofidevo/astro-dynamic-header
Advanced tools
A dynamic Astro header component that switches between floating and fullscreen styles
A dynamic, responsive header component for Astro projects that can switch between floating and fullscreen styles with multi-level dropdown navigation support.
[!WARNING] Breaking Changes: Version 2.0+ introduces a restructured configuration object. If you are upgrading from an older version, please review the Component Props and the Comprehensive Example to migrate your configuration.
https://base-astro-psi.vercel.app/fullscreen-demo
npm i @sofidevo/astro-dynamic-header
You need to add the Iconify CDN to the head of your project for the hamburger menu icons to work properly:
<script src="https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js"></script>
Add this to your main layout or in the <head> section of your Astro pages.
By default, the header uses preset="auto", which automatically detects the theme based on a .dark class on your root element (html or body).
---
import Header from '@sofidevo/astro-dynamic-header/Header';
const = menuItems: [
{ link: '/about', text: 'About' },
]
---
<!-- Detects .dark class on root automatically -->
<Header navigation={{ menuItems }} />
You can provide custom colors for both light and dark modes simultaneously.
---
import Header from '@sofidevo/astro-dynamic-header/Header';
const navigation = {
menuItems: [
{ link: '/about', text: 'About' },
]
};
const theme = {
light: {
accentColor: "#3e1c71",
backgroundColor: "rgba(255, 255, 255, 0.8)"
},
dark: {
accentColor: "#00ffff",
backgroundColor: "rgba(20, 20, 20, 0.9)"
}
};
---
<Header
preset="auto"
theme={theme}
navigation={navigation}
/>
| Prop | Type | Default | Description |
|---|---|---|---|
headerType | "floating" | "fullscreen" | "floating" | Header layout style |
preset | "light" | "dark" | "auto" | "auto" | Theme behavior. auto follows root class. |
logo | LogoConfig | {} | Logo configuration object |
navigation | NavConfig | {} | Navigation configuration object |
theme | DualThemeConfig | {} | Custom theme overrides for light/dark |
classNames | CustomClassNames | {} | Custom class names for CSS Modules |
| Propery | Type | Description |
|---|---|---|
light | ThemeConfig | Styles applied in light mode |
dark | ThemeConfig | Styles applied in dark mode |
| Propery | Type | Default |
|---|---|---|
backgroundColor | string | Preset default |
backgroundColorOpaque | string | Preset default |
backdropBlur | string | "blur(20px)" |
zIndex | number | 10 |
textColor | string | Preset default |
accentColor | string | Preset default |
[!IMPORTANT] Transparency vs Solid Submenus: To ensure the best UI and avoid rendering bugs with
backdrop-filteron nested elements, submenus and the mobile navigation panel are solid/opaque.If you use a transparent
backgroundColor(e.g.,rgba), remember to also provide its solid counterpart inbackgroundColorOpaque.
<Header theme={{
light: {
backgroundColor: "rgba(255, 255, 255, 0.7)", // Transparent header body
backgroundColorOpaque: "#ffffff", // Solid submenus
}
}} />
The classNames prop allows you to inject custom CSS classes (such as Tailwind CSS utility classes) into specific high-level elements of the Header component. This provides a bridge between the component's internal styles and your project's global styling system.
| Property | Target Element | Purpose & Common Use Cases |
|---|---|---|
container | Outer div wrapping the header | Positioning & Layout: Use for top-0, z-50, fixed, or adjusting the max-width and mx-auto logic. |
header | Inner <header> element | Appearance: The best place for shadows (shadow-md), borders (border-b), or custom transition durations. |
logo | <a> tag surrounding the logo | Interactions: Add hover states, custom focus rings, or adjust the flex alignment of the logo group. |
logoText | <span> tag containing the logo text | Typography: Override font weights, apply text shadows, or use specific tracking/leading classes. |
nav | div wrapping the desktop navigation items | Desktop Layout: Adjust spacing between the logo and the menu, or add responsive visibility classes (hidden md:flex). |
Implementing a Premium Shadow & Border (Tailwind): Ideal for creating a modern "glass" effect with a subtle border and shadow that adapts to dark mode.
<Header
classNames={{
header: "shadow-xl border-b border-black/5 dark:border-white/10 transition-all duration-500",
container: "top-4 px-6"
}}
/>
Custom Typography for Logo & Nav Spacing: Perfect for matching the header with your brand's specific typography and layout requirements.
<Header
classNames={{
logoText: "tracking-tighter font-black italic uppercase",
nav: "ml-auto gap-8" /* Moves menu to the right and increases gap */
}}
/>
[!TIP] Since these classes are injected using Astro's
class:list, you can also pass objects or arrays if you need conditional logic for your custom classes.
| Property | Type | Description |
|---|---|---|
src | string | URL of the logo image |
alt | string | Alternative text for the logo image |
width | string | Width of the logo (e.g., "50px", "5rem") |
text | string | Text to display next to or instead of logo image |
textSize | string | Font size for the logo text |
textColor | string | Color for the logo text |
| Property | Type | Description |
|---|---|---|
homeUrl | string | URL for the home link (defaults to /) |
menuItems | MenuItem[] | Array of navigation menu items |
| Property | Type | Description |
|---|---|---|
link | string | URL the menu item points to |
text | string | Label text for the menu item |
submenu | SecondaryMenuItem[] | Optional array of nested menu items |
The Header component provides a flexible slot system that allows you to add additional content:
| Slot Name | Location | Visibility | Description |
|---|---|---|---|
actions | Header & Mobile panel | Responsive visibility | Add action buttons (login, signup, etc.) |
---
import Header from '@sofidevo/astro-dynamic-header/Header';
const navigation = {
menuItems: [{ link: '/about', text: 'About' }]
};
---
<Header navigation={navigation}>
<div slot="actions">
<button class="login-btn">Login</button>
</div>
</Header>
Below is a complete implementation example showcasing custom logo configuration, navigation with a home URL, and theme overrides.
---
import Header from '@sofidevo/astro-dynamic-header/Header';
const menuItems = [
{
link: "#",
text: "Services",
submenu: [
{ link: "/design", text: "Design" },
{ link: "/consulting", text: "Consulting" },
{
link: "#",
text: "Web Development",
submenu: [
{ link: "/web/frontend", text: "Frontend" },
{ link: "/web/backend", text: "Backend" },
{ link: "/web/fullstack", text: "Full Stack" },
],
},
],
},
{ link: "/about", text: "About" },
{ link: "/contact", text: "Contact" },
];
const theme = {
light: {
accentColor: "#ff0000",
backgroundColor: "rgba(255, 255, 255, 0.8)",
},
dark: {
accentColor: "#00ffff",
backgroundColor: "rgba(20, 20, 20, 0.9)",
},
};
---
<Header
headerType="floating"
preset="dark"
logo={{
src: "https://itssofi.dev/img/icons/sofi-icon.webp",
alt: "My Site Logo",
width: "44px",
}}
navigation={{
homeUrl: "/",
menuItems: menuItems,
}}
theme={theme}
>
<button slot="actions">Login</button>
</Header>
The component uses CSS custom properties that you can override:
:root {
--light-spot-color: #00ffff;
--color-tertiary: #ffffff;
--color-hamburger-lines: #ffffff;
}
The package provides full TypeScript support. You can import types to ensure your configuration is correct:
---
import Header from '@sofidevo/astro-dynamic-header/Header';
import type {
NavConfig,
DualThemeConfig,
MenuItem,
SecondaryMenuItem
} from '@sofidevo/astro-dynamic-header';
const navigation: NavConfig = {
menuItems: [
{
link: '/products',
text: 'Products',
submenu: [
{ link: '/software', text: 'Software' },
{ link: '/hardware', text: 'Hardware' }
]
}
]
};
const theme: DualThemeConfig = {
light: {
accentColor: "#3e1c71",
backgroundColor: "rgba(255, 255, 255, 0.8)",
backgroundColorOpaque: "#ffffff"
},
dark: {
accentColor: "#00ffff",
backgroundColor: "rgba(10, 10, 10, 0.9)",
backgroundColorOpaque: "#0a0a0a"
}
};
---
<Header
navigation={navigation}
theme={theme}
preset="auto"
/>
| Type | Description |
|---|---|
MenuItem | Top-level menu item with optional properties |
SecondaryMenuItem | Second-level menu item |
TertiaryMenuItem | Third-level menu item |
NavConfig | Main navigation configuration object |
ThemeConfig | Individual theme settings (colors, blur, etc.) |
DualThemeConfig | Combined settings for light and dark modes |
LogoConfig | Logo image and text configuration |
HeaderProps | Main props for the Header component |
backdrop-filter for glassmorphism.dark classIf you encounter import errors, try these solutions:
Use direct subpath import:
import Header from '@sofidevo/astro-dynamic-header/Header';
Check relative imports in TS:
In some environments (like node16), you might need to use the .js extension even for TypeScript files when importing from the package internals, though the main entry point handles this for you.
Verify TypeScript configuration:
// tsconfig.json
{
"compilerOptions": {
"moduleResolution": "bundler",
"allowImportingTsExtensions": true
}
}
Visit our demo website to see the component in action with interactive examples and complete documentation.
MIT License - see the LICENSE file for details.
If you find this package helpful, please consider giving it a star on GitHub!
FAQs
A dynamic Astro header component that switches between floating and fullscreen styles
We found that @sofidevo/astro-dynamic-header demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.