@sofidevo/astro-dynamic-header

v1.0.34

Published

a month ago

A dynamic Astro header component that switches between floating and fullscreen styles

0High
0Medium
0Low

sofidevo

astro component header navigation responsive typescript dynamic floating sofidev astro-component withastro fullscreen

@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 |

Menu Item Structure

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!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sofidevo/astro-dynamic-header

Features

Live demo

Installation

Required Dependencies

Quick Start

Basic Usage

TypeScript Configuration

Advanced Usage

Component Props

Header Component

Menu Item Structure

Slots Support

Available Slots

Actions Slot Behavior

Slot Examples

Using the Actions Slot

Complete Example with All Props

Styling Action Buttons

Header Types

Floating Header

Fullscreen Header

Styling and Customization

TypeScript Support

Browser Support

Troubleshooting

Import Issues

Compatibility

Live Examples

Testing

Running Tests

Test Coverage

Component Logic Tests

Integration Tests (7 tests)

Test Technologies

License

Support