@sofidevo/astro-dynamic-header

A dynamic, responsive header component for Astro projects that can switch between floating and fullscreen styles with multi-level dropdown navigation support.

Features

Dynamic Styles: Switch between floating and fullscreen header layouts
Fully Responsive: Mobile-first design with hamburger menu
Multi-level Dropdowns: Support for nested navigation menus
Slot Support: Customizable slots for desktop header and mobile panel content
TypeScript Support: Full type safety and IntelliSense
Customizable: Extensive customization options for colors, sizes, and behavior
Astro Optimized: Built specifically for Astro framework

Live demo

https://base-astro-psi.vercel.app/fullscreen-demo

Installation

 npm i @sofidevo/astro-dynamic-header

Required Dependencies

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.

Quick Start

Basic Usage

---
// Option 1: Import from direct subpath (recommended)
import Header from '@sofidevo/astro-dynamic-header/Header';

// Option 2: Import from main entry point with types
import { HeaderProps, type MenuItemType } from '@sofidevo/astro-dynamic-header';

const menuItems = [
  { link: '/about', text: 'About' },
  { link: '/contact', text: 'Contact' },
];
---

<Header
  headerType="floating"
  logoSrc="/logo.png"
  menuItems={menuItems}
/>

TypeScript Configuration

To ensure imports work correctly in your Astro project, make sure your tsconfig.json has the appropriate configuration:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "strict": true,
    "noEmit": true,
    "jsx": "preserve"
  },
  "extends": "astro/tsconfigs/strict"
}

Advanced Usage

---
import Header from '@sofidevo/astro-dynamic-header/Header';
import type { MenuItemType } from '@sofidevo/astro-dynamic-header';

const menuItems = [
  {
    link: '#',
    text: 'Services',
    submenu: [
      {
        link: '#',
        text: 'Web Development',
        submenu: [
          { link: '/web/frontend', text: 'Frontend' },
          { link: '/web/backend', text: 'Backend' },
          { link: '/web/fullstack', text: 'Full Stack' },
        ],
      },
      { link: '/design', text: 'Design' },
      { link: '/consulting', text: 'Consulting' },
    ],
  },
  { link: '/about', text: 'About' },
  { link: '/contact', text: 'Contact' },
];
---

<Header
  headerType="fullscreen"
  logoSrc="/logo.png"
  logoAlt="My Company"
  logoWidth="150px"
  homeUrl="/"
  menuItems={menuItems}
  backgroundColor="#000000dd"
  backdropBlur="blur(15px)"
  zIndex={100}
/>

Component Props

Header Component

Prop	Type	Default	Description
`headerType`	`"floating" \| "fullscreen"`	`"floating"`	Header layout style
`logoSrc`	`string`	`"/logo.png"`	Logo image source
`logoAlt`	`string`	`"Logo"`	Logo alt text
`logoWidth`	`string`	`"55px"`	Logo width
`logoText`	`string`	`"Your logo text"`	Text displayed next to the logo
`logoTextSize`	`string`	`"1em"`	Font size for logo text
`logoTextColor`	`string`	`"#ffffff"`	Color for logo text
`homeUrl`	`string`	`"/"`	Home page URL
`menuItems`	`MenuItemType[]`	`[]`	Navigation menu items
`backgroundColor`	`string`	`"#0d0d0dcc"`	Header background color
`backdropBlur`	`string`	`"blur(20px)"`	Backdrop filter blur
`zIndex`	`number`	`10`	CSS z-index value

interface MenuItemType {
  link: string;
  text: string;
  submenu?: MenuItemType[];
}

Slots Support

The Header component provides a flexible slot system that allows you to add additional content:

Available Slots

Slot Name	Location	Visibility	Description
`actions`	Header & Mobile panel	Responsive visibility	Add action buttons (login, signup, etc.) that appear in both desktop and mobile

Actions Slot Behavior

The actions slot is intelligent and automatically manages visibility:

Desktop (≥768px): Shows actions in the main header after navigation
Mobile (<768px): Shows same actions inside the mobile menu panel
Automatic hiding: Desktop version is hidden on mobile, mobile version is hidden on desktop

Slot Examples

Using the Actions Slot

---
import Header from '@sofidevo/astro-dynamic-header/Header';

const menuItems = [
  { link: '/about', text: 'About' },
  { link: '/contact', text: 'Contact' },
];
---

<Header
  headerType="floating"
  logoSrc="/logo.png"
  logoText="My Company"
  menuItems={menuItems}
>
  <div slot="actions">
    <button class="login-btn">Login</button>
    <button class="signup-btn">Sign Up</button>
  </div>
</Header>

Complete Example with All Props

---
import Header from '@sofidevo/astro-dynamic-header/Header';

const menuItems = [
  { link: '/about', text: 'About' },
  { link: '/services', text: 'Services' },
  { link: '/contact', text: 'Contact' },
];
---

<Header
  headerType="fullscreen"
  logoSrc="/logo.png"
  logoAlt="My Company"
  logoWidth="60px"
  logoText="My Company"
  logoTextSize="1.2em"
  logoTextColor="#ffffff"
  homeUrl="/"
  menuItems={menuItems}
  backgroundColor="#000000dd"
  backdropBlur="blur(15px)"
  zIndex={100}
>
  <div slot="actions" class="header-actions">
    <button class="btn btn-outline">Login</button>
    <button class="btn btn-primary">Get Started</button>
  </div>
</Header>

Styling Action Buttons

.header-actions {
  display: flex;
  gap: 0.5em;
  align-items: center;
}

.btn {
  padding: 0.5em 1em;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  font-weight: 500;
  text-decoration: none;
  display: inline-flex;
  align-items: center;
  transition: all 0.2s ease;
}

.btn-outline {
  background: transparent;
  color: #ffffff;
  border: 1px solid #ffffff;
}

.btn-outline:hover {
  background: #ffffff;
  color: #000000;
}

.btn-primary {
  background: #00ffff;
  color: #000000;
}

.btn-primary:hover {
  background: #00cccc;
}

Header Types

Floating Header

Centered with max-width constraint
Rounded corners
Padding around container
Perfect for modern, card-like designs

Fullscreen Header

Full viewport width
No border radius
Edge-to-edge design
Ideal for traditional website layouts

Styling and Customization

The component uses CSS custom properties that you can override:

:root {
  --light-spot-color: #00ffff;
  --color-tertiary: #ffffff;
  --color-hamburger-lines: #ffffff;
}

TypeScript Support

Full TypeScript support with exported interfaces:

import type {
  MenuItemType,
  HeaderProps,
  NavMenuProps,
  MobileNavProps,
  HamburgerButtonProps
} from '@sofidevo/astro-dynamic-header';

Browser Support

All modern browsers
Mobile responsive design
Supports CSS backdrop-filter
Graceful degradation for older browsers

Troubleshooting

Import Issues

If you encounter import errors, try these solutions:

Use direct subpath import:

import Header from '@sofidevo/astro-dynamic-header/Header';

Verify TypeScript configuration:

// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "nodenext"
    "allowImportingTsExtensions": true
  }
}

Import types separately:

---
import Header from '@sofidevo/astro-dynamic-header/Header';
import type { MenuItemType } from '@sofidevo/astro-dynamic-header';
---

Compatibility

Astro 4.x and 5.x
SSG Projects (Static Site Generation)
SSR Projects (Server-Side Rendering)
Hybrid Projects (output: 'hybrid')

Live Examples

Visit our demo website to see the component in action with interactive examples and complete documentation.

Testing

This project includes a comprehensive test suite with 34 tests covering all critical functionality.

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test Coverage

The test suite covers:

Component Logic Tests

Header Component (4 tests): Hamburger controller functionality, menu toggle behavior
HamburgerButton Component (10 tests): Button states, responsive behavior, accessibility
MobileNav Component (7 tests): Dropdown structure, nested submenus, conditional rendering
NavMenu Component (6 tests): Dynamic positioning, submenu interactions, viewport adjustments

Integration Tests (7 tests)

Component interaction flows
Responsive behavior between mobile/desktop
Keyboard navigation and accessibility
Menu state management during navigation

Test Technologies

Vitest: Fast testing framework
jsdom: DOM simulation for component testing
TypeScript: Type-safe test writing

License

MIT License - see the LICENSE file for details.

Support

If you find this package helpful, please consider giving it a star on GitHub!

SofiDevO/astro-dynamic-header