AppHeader Component

A Vue component for the App Header of the City of Philadelphia's web applications — top trusted-site banner, main navbar (branding, links, search, mobile burger menu), and an optional alert banner.

Features

• 🎯 TypeScript support with full type definitions
• 🎨 Customizable options for sticky nav, showing / hiding trusted site, slots for mobile menu, navbar branding, nav links and search
• ♿ Accessibility features: ARIA roles, keyboard navigation
• 📏 Responsive design for mobile and desktop

Installation

pnpm add @phila/phila-ui-app-header @phila/phila-ui-core
# or
npm install @phila/phila-ui-app-header @phila/phila-ui-core

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Usage

<script setup lang="ts">
import { AppHeader } from "@phila/phila-ui-app-header";
import MyMobileMenu from "./MyMobileMenu.vue";
import MyTranslationComponent from "./MyTranslationComponent.vue";
import MyServicesComponent from "./MyServicesComponent.vue";

const navLinks = [
  {
    text: "Services",
    href: "/services",
    subNav: MyServicesComponent,
  },
  {
    text: "Departments",
    href: "/departments",
    subLinks: [
      { text: "Department 1", href: "/departments/department-1" },
      { text: "Department 2", href: "/departments/department-2" },
    ],
  },
  {
    text: "About",
    href: "/about",
  },
];
const navbarBrand = {
  brandingImage: {
    href: "/",
    src: "https://www.phila.gov/assets/images/city-of-philadelphia-logo-medium-white.png",
    altText: "City of Philadelphia",
  },
  brandingLink: {
    text: "Mayor Cherelle L. Parker",
    href: "https://phila.gov/departments/mayor",
  },
};
</script>

<template>
  <AppHeader :sticky="true" :show-trusted-site="true" :links="navLinks" :navbar-brand="navbarBrand">
    <template #mobile-nav>
      <MyMobileMenu />
    </template>
    <template #translations>
      <MyTranslationComponent />
    </template>
  </AppHeader>
</template>

Props

| Prop | Type | Default | Description | | ----------------- | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | "main-nav" | Base id used to derive internal element ids and the visibility group for the burger/search/links. | | sticky | boolean | true | Whether the navbar stays fixed to the top of the viewport on desktop. | | compactMobile | boolean | false | Uses shorter mobile sizing (navbar, burger, logo, trusted banner) below 1024px. | | navbarBrand | NavbarBrandProps | undefined | { brandingImage?: {src, href, altText}, brandingLink?: {text, href}, logo?: Partial<LogoProps> } — renders the default branding block. Omit and use the navbar-brand slot instead for full control. | | links | NavLink[] | undefined | { text, href, subLinks?, subNav? }[] — top-level nav links. subNav renders a custom flyout component; subLinks renders a plain link list. | | showTrustedSite | boolean | true | Shows/hides the ".gov" trusted-site banner above the navbar. | | bannerTitle | string | undefined | Title for the optional AlertBanner shown below the navbar. | | bannerMessage | string | undefined | Message for the optional AlertBanner. The banner only renders if bannerTitle or bannerMessage is set. | | translations | Component | undefined | Component rendered in the trusted-site banner's translation slot when languages isn't set and the translations slot isn't used. | | languages | Language[] | undefined | { code, title, lang? }[] — when set, renders the built-in LanguageSwitcher instead of translations. | | locale | string | undefined | Currently selected language code, paired with the update:locale emit. | | className | string | undefined | Additional CSS classes. |

Slots

Most consumers only need translations, mobile-nav, and possibly navbar-end. The rest are escape hatches that replace an entire section of the navbar for full control.

| Slot | Description | | --------------- | ------------------------------------------------------------------------------------------------------------ | | translations | Replaces the translation control in the trusted-site banner (falls back to languages/translations prop). | | mobile-nav | Content rendered inside the mobile burger menu. | | search-panel | Content rendered inside the navbar's search flyout. | | navbar-end | Extra content at the far end of the navbar (only rendered if provided). | | navbar-toggle | Replaces the entire mobile burger button (default renders NavbarBurger + mobile-nav). | | navbar-left | Replaces the entire left side of the navbar (default renders navbar-brand). | | navbar-brand | Replaces just the branding block (default renders NavbarBrand from the navbarBrand prop). | | navbar-right | Replaces the entire right side of the navbar (default renders navbar-links + navbar-search). | | navbar-links | Replaces the nav links block (default renders NavbarLinks from the links prop). | | navbar-search | Replaces the search block (default renders NavbarSearch wrapping the search-panel slot). |

Events

| Event | Payload | Description | | --------------- | -------- | ----------------------------------------------------------------- | | update:locale | string | Emitted with the selected language code from LanguageSwitcher |

Flyout sub-navigation

The NavBar component supports flyout sub-navigations. You can provide a Vue component for the subNav property of a nav link to render custom content in the flyout. Your component should be wrapped by the nav-flyout class so it can be positioned correctly below the navbar.

<template>
  <div class="nav-flyout">
    <h3>Custom Sub-Navigation</h3>
    <ul>
      <li><a href="/custom-link-1">Custom Link 1</a></li>
      <li><a href="/custom-link-2">Custom Link 2</a></li>
    </ul>
  </div>
</template>

Other exports

AppHeader composes several components also exported individually for advanced use: NavBar, NavbarBrand, NavbarBrandLogo, NavbarBurger, NavbarSearch, NavbarLinks, AlertBanner, TrustedSite, LanguageSwitcher, and NavbarInfo (not currently wired into AppHeader's own props — use it directly if you need an info tooltip elsewhere).

Development

Install Dependencies

pnpm install

Run Demo

pnpm dev

Build Library

pnpm build

Type Check

pnpm type-check

Test locally in your development environment

npm pack
cp ./dist/*.tgz ~/path/to/your/local/npm/repo
cd ~/path/to/your/local/npm/repo
npm install *.tgz

Publishing to NPM

Follow the release instructions using changesets.

License

MIT