# 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:

- `navbar` renders text links and action-style links.
- `socials` renders compact icon-only links after the navbar.

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

```ts title="src/theme.config.ts"
export default defineLotusConfig({
  navbar: [
    { 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-lotus',
      external: true,
      icon: 'github',
    },
    {
      label: 'X',
      href: 'https://x.com/prosefly',
      external: true,
      icon: 'x',
    },
  ],
});
```

## Navbar Items

Every navbar item needs a `label` and `href`.

```ts
navbar: [
  { 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-lotus',
  external: true,
}
```

## Action Links

Set `variant` when a navbar 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 Lotus
aliases such as `external`.

<Callout type="note" title="Leading icons">
  The public navbar 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 `navbar` data.
</Callout>

## Social Links

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

```ts
socials: [
  {
    label: 'GitHub',
    href: 'https://github.com/prosefly/astro-theme-lotus',
    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 Lotus
aliases such as `github`, `x`, `discord`, and `external`.

## Translated Labels

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

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

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

## Mobile Behavior

On desktop, the header renders navbar links, social links, search, language
select, and the theme switch inline.

On mobile:

- Search stays in the compact header.
- Navbar links, action links, socials, language select, and the theme switch
  move into the mobile menu.
- 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` |
| Custom theme switch placement | `ThemeSwitch` or `HeaderSocialIcons` |

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