https://github.com/sofidevo/astro-dynamic-header
dynamic header component for astro
https://github.com/sofidevo/astro-dynamic-header
astro astrobuild astrojs npm npm-package
Last synced: 10 months ago
JSON representation
dynamic header component for astro
- Host: GitHub
- URL: https://github.com/sofidevo/astro-dynamic-header
- Owner: SofiDevO
- License: mit
- Created: 2025-08-19T22:57:04.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-29T03:31:05.000Z (10 months ago)
- Last Synced: 2025-08-29T06:34:46.753Z (10 months ago)
- Topics: astro, astrobuild, astrojs, npm, npm-package
- Language: Astro
- Homepage: https://www.npmjs.com/package/@sofidevo/astro-dynamic-header
- Size: 35.7 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @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
- 🚀 **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](https://base-astro-psi.vercel.app/fullscreen-demo)
## Installation
```bash
npm i @sofidevo/astro-dynamic-header
```
## Quick Start
### Basic Usage
```astro
---
// 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' },
];
---
```
### TypeScript Configuration
To ensure imports work correctly in your Astro project, make sure your `tsconfig.json` has the appropriate configuration:
```json
{
"compilerOptions": {
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"strict": true,
"noEmit": true,
"jsx": "preserve"
},
"extends": "astro/tsconfigs/strict"
}
```
### Advanced Usage
```astro
---
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' },
];
---
```
## 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` | `"120px"` | Logo width |
| `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
```typescript
interface MenuItemType {
link: string;
text: string;
submenu?: MenuItemType[];
}
```
## 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:
```css
:root {
--light-spot-color: #00ffff;
--color-tertiary: #ffffff;
--color-hamburger-lines: #ffffff;
}
```
## TypeScript Support
Full TypeScript support with exported interfaces:
```typescript
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:
1. **Use direct subpath import:**
```astro
import Header from '@sofidevo/astro-dynamic-header/Header';
```
2. **Verify TypeScript configuration:**
```json
// tsconfig.json
{
"compilerOptions": {
"moduleResolution": "bundler", // or "nodenext"
"allowImportingTsExtensions": true
}
}
```
3. **Import types separately:**
```astro
---
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
```bash
# 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](./LICENSE) file for details.
## Support
If you find this package helpful, please consider giving it a ⭐ on GitHub!