Skip to main content

Anchor

A fundamental component for rendering links to external addresses.

When to use

  • Link to an external URL: docs, marketing pages, third-party sites.
  • Link to a file, or to a mailto: or tel: address.
  • Prefer Button when the control runs an action and does not navigate.
  • Prefer Breadcrumb when the links show the path from a root page to the current page.

When not to use

  • Internal application routes: prefer the framework router's link primitive (react-router <Link>) so client-side navigation kicks in. Keep mantle's styling by composing (see Polymorphism).
  • For triggering an action: use a Button instead. If it doesn't navigate, it's not a link.

Icons

Pass icon (a phosphor or custom SVG) and optionally iconPlacement ("start" default, or "end") to render a small inline icon. It suits "external link" or "download" affordances. Icons are decorative; the link text must still describe the destination on its own.

Security

When target="_blank" and rel is omitted, the anchor renders rel="noopener noreferrer". A rel you pass is used as-is. The rel prop accepts an array: duplicates are de-duped and sorted, so it's safe to merge token sets.

Accessibility

Link text must be self-describing: avoid "click here" / "read more". The icon is decorative by default: it renders aria-hidden unless the SVG carries aria-label, aria-labelledby, role, or an explicit aria-hidden. For icon-only links, pass an aria-label.

Polymorphism

Use the asChild prop to compose the Anchor styling onto another element, most commonly a react-router <Link> for internal, client-side navigation.

API Reference

Anchor

Anchor renders a native <a> with mantle's link styling and focus treatment. Its href can address a web page, a file, an email address, a location on the same page, or anything else a URL can address. See the MDN docs for more information.

All props from a, plus:

PropTypeDefaultDescription
icon?ReactNodeAn icon to render inside the anchor. Decorative by default: rendered aria-hidden unless the SVG carries a name, a role, or an explicit aria-hidden.
iconPlacement?"start" | "end""start"The side that the icon will render on, if one is present.
rel?string | (string | null | undefined)[]"noopener noreferrer" when target="_blank", else noneThe relationship between the linked resource and the current document. An array is trimmed, de-duplicated, sorted, and joined with a space.
asChild?booleanfalseUse the asChild prop to compose the Anchor styling onto alternative element types or your own React components.

Data attributes

Data AttributeValueDescription
data-slot"anchor"On the anchor element. Stable styling hook that survives a className override or an asChild swap.
data-slot"anchor-label"On the inline <span> wrapping children, between the two icon slots. Target it to style the text.