# SiteHeader

> Combined announcement bar + navbar with full design freedom via data-lx-header/data-lx-nav tags.

Canonical URL: https://fa7e86e3d553:3005/islands/navigation/site-header

> Combined announcement bar + navigation in one fixed header. Two modes: **Hydration mode** (data-lx tags — any design) or **Legacy mode** (props-driven rendering).

## Preview

**Category**: Navigation

---

## Hydration Mode (Recommended)

Generate any HTML/CSS for your header. Place `data-lx-header` tags for announcement features and `data-lx-nav` tags for navigation. Gets all Navbar behaviors + announcement rotation/dismiss.

### Required Tags

| Tag | Required | Purpose |
|-----|----------|---------|
| `data-lx-header="root"` | Yes | Root header element (spacer + sticky) |
| `data-lx-nav="cart-trigger"` | Yes* | Cart button |
| `data-lx-nav="cart-count"` | Yes* | Cart badge (auto-updated) |
| `data-lx-nav="mobile-trigger"` | Yes | Hamburger toggle |
| `data-lx-nav="mobile-panel"` | Yes | Mobile menu container |

*Not required if `hideCart: true` in props.

### Optional Tags

| Tag | Purpose |
|-----|---------|
| `data-lx-nav="root"` | Alternative root for nav-only behavior |
| `data-lx-nav="logo"` | Logo (informational) |
| `data-lx-nav="dropdown-trigger"` | Dropdown hover trigger |
| `data-lx-nav="dropdown-panel"` | Dropdown content |
| `data-lx-header="announcement"` | Announcement bar container (hidden on dismiss) |
| `data-lx-header="announcement-text"` | Text element — cycles through messages |
| `data-lx-header="announcement-dismiss"` | Close button — persists to sessionStorage |

### Behavior Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| sticky | boolean | true | Fixed position header |
| cartMode | "drawer" \| "link" | "drawer" | Cart click behavior |
| cartUrl | string | "/cart" | URL for link mode |
| transparent | boolean | false | Transparent bg until scroll |
| offsetTop | string | "0" | Top offset |
| messages | string[] | - | Announcement rotation texts |
| rotateInterval | number | 4000 | Ms between rotations |
| dismissible | boolean | false | Show dismiss X, persist to sessionStorage |
| hideCart | boolean | false | Skip cart tag requirements |

### Full Example (Hydration Mode)

```html
<lx-island name="SiteHeader">
  <script type="application/json">
{
  "navbar": {
    "logo": {},
    "links": []
  }
}
  </script>
</lx-island>
```

### CSS Contract

```css
[data-lx-nav="mobile-panel"] { display: none; }
[data-lx-nav="mobile-panel"].lx-open { display: block; }
```

### Announcement Behavior

- `messages` array cycles text in `data-lx-header="announcement-text"` element
- Dismissed state persists in `sessionStorage._lx_ann_dismissed`
- On page load, if previously dismissed → announcement container hidden
- If only 1 message → no rotation, just static text

---

## Legacy Mode (Props-Driven)

If no `data-lx-header` or `data-lx-nav` tags found, renders from props.

### Props (Legacy)

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| announcement | object | No | `{messages[], speed?, backgroundColor?, textColor?, dismissible?, link?}` |
| navbar | object | Yes | `{logo, links[], cartCount?, transparent?, style?, cta?, hideCart?}` |
| sticky | boolean | No | Default true |

### Legacy Example

```html
<lx-island name="SiteHeader">
  <script type="application/json">
{
  "navbar": {
    "logo": {},
    "links": []
  }
}
  </script>
</lx-island>
```

---

## Validation

Hydration mode (publish validator):
- `data-lx-header="root"` OR `data-lx-nav="root"` must exist
- `data-lx-nav="cart-trigger"` + `data-lx-nav="cart-count"` required (unless hideCart)
- `data-lx-nav="mobile-trigger"` + `data-lx-nav="mobile-panel"` required

## Why SiteHeader over separate Navbar + AnnouncementBar?

- No `offsetTop` coordination needed — single sticky container
- Announcement dismiss smoothly collapses without layout shift
- One island = one hydration pass (better perf)
- ResizeObserver keeps spacer height correct as announcement shows/hides

## Related Islands

- [Navbar](/islands/navigation/navbar) — Standalone nav (when no announcement needed)
- [Footer](/islands/navigation/footer) — Page footer (also supports hydration mode)
- [CartDrawer](/islands/cart/cart-drawer) — Legacy Cart V1 only; new pages
  use the configured Cart V2 profile
- [AnnouncementBar](/islands/navigation/announcement-bar) — Standalone (use SiteHeader instead for combined)