Reference

Link

Create links with native attributes, locale-aware internal URLs and explicit handling for downloads or resolved destinations.

A native anchor with locale-aware internal URLs and noopener for new-tab navigation. Its default plain variant adds no appearance or browser JavaScript. Use it for navigation; use Button’s native button mode for actions.

Availability and placement

Included in every generated project at src/components/Link/index.astro. Place navigation inside the owning section or its reusable child. This complete example can live in src/sections/HomeLink/index.astro.

Complete example

---
import Link from '@/components/Link/index.astro'
import { getDictionary } from '@/i18n'

const { buttons } = getDictionary(Astro.currentLocale)
---

<Link href='/' variant='text'>
  {buttons.backHome}
</Link>

Expected result: a normal homepage anchor. With the default configuration, en-us links to /; an active es-mx locale links to /es-mx/. The current locale comes from Astro.currentLocale; do not pass it as a prop.

API

PropDefaultPurpose
variant?: 'plain' | 'text' | 'nav'plainShared contextual or navigation states.
href?: string—Destination URL or fragment; alternative to routeName.
routeName?: RouteName—Named destination from src/config/routes.ts; alternative to href.
localize: booleantrueLocalize eligible root-relative internal paths.
currentMatch?: 'exact' | 'descendants'UnsetOpt into route-based aria-current, independently of appearance.
Native anchor attributes—target, rel, download, class, aria-*, etc.
Default slot—Content that names the destination.

Which URLs change?

InputBehavior
/contact?from=home#formUses Astro’s locale URL helper and preserves query/hash. Create that page first.
/es-mx/contact with es-mx activePreserved; no second locale prefix.
https://…, //…, mailto:…, tel:…Preserved.
contact, #details, ?page=2Preserved as a browser-relative URL.
A link with an active download attributePreserved as a resource URL.
An explicit href with localize={false}Preserved exactly.

Link formats a URL; it does not create the destination, verify it exists, or translate a content slug. For API/CMS content with translated slugs, resolve the real destination first and pass localize={false}. Follow the project’s localized-content guide for that integration.

Public assets also need localize={false} unless download is active. For a project PDF, first create public/docs/guide.pdf, add downloadGuide: string to src/i18n/dictionaries/<default-locale>/buttons/types.ts, and add a translated downloadGuide value to the buttons domain of every available locale. Then, with Link and buttons already in scope:

<Link href='/docs/guide.pdf' download>
  {buttons.downloadGuide}
</Link>

This is a customization fragment: the PDF and downloadGuide key are deliberately not part of the starter. Do not paste it before completing those two additions.

Targets, styles and limits

target='_blank' adds noopener if absent and retains supplied rel tokens. Add noreferrer yourself when you need that policy. The slot normally supplies the accessible name; icon-only links need a translated aria-label on the link. Attributes and Astro scope attributes reach the anchor.

Use Button with href for button-like navigation. If PageLoader is selected, data-page-loader-skip suppresses its navigation indicator. No prefetch policy, disabled link simulation, or click handler is added.

URL construction belongs to Astro internationalization and its URL helpers.

Shared text and navigation states

Use variant='text' for an underlined contextual link in the accent palette, or variant='nav' for a navigation item inheriting its surrounding color. Both include hover, focus-visible and active states. Nav styles the resulting aria-current value; matching remains an independent choice. Plain remains the default for custom designs and Button composition. Do not use aria-pressed for navigation. Layout stays with the consuming section.

Opt into current-route matching

Leave currentMatch unset to retain caller-owned aria-current. Set it to exact for a page link or descendants for a section link that should remain current on its detail routes. Appearance does not opt a link into matching: a plain link with a custom design can use the same route contract as a nav link.

With Link already imported and after creating the corresponding articles routes, this customization fragment marks the section on its own page and child pages. The label comes from the project’s existing translated content:

<Link href='/articles' currentMatch='descendants' variant='nav'>
  {label}
</Link>

label is illustrative; supply an actual dictionary value from your section. Matching uses the final localized URL and the current page URL:

  • The exact pathname receives aria-current='page'; a descendant receives location. Trailing slashes are normalized and query parameters are ignored.
  • Descendants require a segment boundary: /articles-new is not inside /articles. Different origins and other locale prefixes do not match.
  • The homepage stays exact-only, including its configured base and locale root.
  • A destination with a fragment requires the same page and fragment, and receives location. Requests do not contain URL fragments, so static/server HTML cannot identify an active fragment from the request.
  • An explicit aria-current, including 'false', takes precedence. Query-based tabs, named route groups with nonhierarchical URLs and other non-path identity rules should leave matching unset and supply their own value. Prefer the most specific matching entry within one navigation set rather than marking every ancestor current.

No browser controller, global listener or script is added. Static output records the route at build time; on-demand output uses the render request. Read-only route matching does not require a server adapter.

Inside a Server Island, the render URL belongs to the isolated request. For parent-page navigation, resolve the real parent context first and supply an explicit aria-current; do not infer it from the island endpoint. See parent query context.

For existing client navigation or cloned menus, the owning controller can import currentDestination from @/components/Link/current. Its arguments are the resolved destination URL, current URL, optional match mode (default exact) and the actual homepage pathname including base/locale (default /), which also limits matching to that path’s scope. It returns 'page', 'location' or undefined without reading or changing the DOM. Reuse this function after the owner’s navigation/clone event; preserve authored overrides and scope updates to that owner’s links. This is an integration point, not automatic hash tracking, scrollspy or a lifecycle manager.

Named routes

Pass routeName={routeNames.home} instead of href to select a destination from src/config/routes.ts in the current locale. Import routeNames from @/config/routes. Named links use Astro’s locale/base formatting and throw if the current translation is unavailable. They compose with variant and currentMatch; localize={false} only affects explicit hrefs. Do not supply both destination props. See localized routes for translated static paths, Main/SEO/LanguagePicker context, and actual CMS translation maps.

Named-page URLs are owned by each language’s src/i18n/dictionaries/<locale>/routes.ts. The shared names/types live in src/config/routes.ts; null marks an unavailable translation. Edit these tables instead of adding a second URL list in the component.