# Navbar

Configure header navigation, action links, social icons, and localized labels.

import { Callout } from '@prosefly/astro-components';

The header is built from two config arrays:

- `siteNav` renders text links and action-style links.
- `socials` renders compact icon-only links after the site nav.

Use `siteNav` for primary destinations such as Docs, Blog, Pricing, or an app
link. Use `socials` for external community and repository links.

```json title="theme.config.json"
{
  "siteNav": [
    { "label": "Docs", "href": "/docs/" },
    {
      "label": "Dashboard",
      "href": "https://app.example.com/",
      "external": true,
      "variant": "solid",
      "color": "accent",
      "trailingIcon": "lucide:chevron-right"
    }
  ],
  "socials": [
    {
      "label": "GitHub",
      "href": "https://github.com/prosefly/astro-theme-dahlia",
      "external": true,
      "icon": "github"
    },
    {
      "label": "X",
      "href": "https://x.com/prosefly",
      "external": true,
      "icon": "x"
    }
  ]
}
```

## Site Nav Items

Every site nav item needs a `label` and `href`.

```ts
siteNav: [
  { label: 'Docs', href: '/docs/' },
  { label: 'Blog', href: '/blog/' },
]
```

Internal links are localized automatically when they point into the docs route.
For example, `/docs/configuration/project/` can become
`/docs/zh-cn/configuration/project/` in the Simplified Chinese locale.

Add `external: true` for links that should open in a new tab.

```ts
{
  label: 'Source',
  href: 'https://github.com/prosefly/astro-theme-dahlia',
  external: true,
}
```

## Action Links

Set `variant` when a site nav item should read as a call to action instead of a
plain text link.

```ts
{
  label: 'Get started',
  href: '/docs/overview/',
  variant: 'solid',
  color: 'accent',
  trailingIcon: 'lucide:chevron-right',
}
```

Supported variants:

| Variant | Use it for |
| --- | --- |
| `text` | Normal navigation links. This is the default. |
| `soft` | Secondary actions that should have a filled surface. |
| `outline` | Secondary actions that need more boundary than `soft`. |
| `solid` | Primary actions such as "Get started" or "Dashboard". |

`color` can be `neutral` or `accent`. Use `accent` sparingly for the primary
action in the header.

## Icons

Navbar action links support `trailingIcon`.

```ts
{
  label: 'Dashboard',
  href: '/dashboard/',
  variant: 'soft',
  trailingIcon: 'lucide:arrow-up-right',
}
```

Use full Iconify names such as `lucide:chevron-right`, or supported Dahlia
aliases such as `external`.

<Callout type="note" title="Leading icons">
  The public site nav config is optimized for text links and trailing action
  icons. If a project needs leading icons, badges, or custom layout, override
  `HeaderNavbar` and reuse the configured `siteNav` data.
</Callout>

## Social Links

`socials` renders compact icon links next to the site nav on desktop and inside
the mobile menu on small screens.

```ts
socials: [
  {
    label: 'GitHub',
    href: 'https://github.com/prosefly/astro-theme-dahlia',
    external: true,
    icon: 'github',
  },
  {
    label: 'Discord',
    href: 'https://discord.gg/prosefly',
    external: true,
    icon: 'discord',
  },
]
```

Social links require `icon`. Icon values can be full Iconify names or Dahlia
aliases such as `github`, `x`, `discord`, and `external`.

## Translated Labels

Use `translations` when the same link should have locale-specific labels.

```ts
siteNav: [
  {
    label: 'Docs',
    href: '/docs/',
    translations: {
      'zh-cn': '文档',
    },
  },
]
```

The fallback label is `label`. Translation keys match Dahlia locale keys.

## Mobile Behavior

On desktop, the header renders site nav links, social links, search, and
language select inline.

On mobile:

- Search stays in the compact header.
- Site nav links, action links, and socials move into the mobile menu.
- The language selector stays in the compact header next to the site brand.
- Action links render full width so they remain easy to tap.

## Custom Rendering

Use config first. Override components only when the markup or placement needs
to change.

| Need | Override |
| --- | --- |
| Custom navbar markup | `HeaderNavbar` |
| Custom social link area | `HeaderSocialIcons` |
| Custom brand link | `SiteBrand` |

See [Overriding Components](/docs/customization/overriding-components/) for the
override contract.