Skip to content
Browse documentation
whisk/ui

Link

Navigate to another resource with accessible link semantics.

Overview

Link renders a native anchor for a real destination, with Whisk/UI typography, underline, focus, and optional rel protection for external destinations.

Use when

Activation changes location or opens a resource.

Use instead

Use Button for an in-place action such as saving, filtering, or opening a dialog.

Usage

import { Link } from "@smoothie-framework/whisk-react";

<Link href="/settings">Open workspace settings</Link>

Examples

Variants

The default underlined primary link is the clearest choice in prose. Use a secondary or ghost treatment only where the surrounding interface already makes the element's destination clear.

import { Link, StackRow } from "@smoothie-framework/whisk-react";

<StackRow gap={4} wrap>
  <Link href="/overview">Primary link</Link>
  <Link href="/activity" variant="secondary" underline="hover">Secondary link</Link>
  <Link href="/help" variant="ghost" underline="none">Ghost link</Link>
</StackRow>

Current page

Use a navigation landmark and mark the link for the page being viewed with aria-current="page". The application router decides which destination is current. Link does not change its visual styling for this attribute; choose the active treatment in application code.

import { Box, Link, Stack } from "@smoothie-framework/whisk-react";

<Box as="nav" aria-label="Settings">
  <Stack as="ul" gap={2}>
    <Box as="li">
      <Link href="/settings" aria-current="page">General settings</Link>
    </Box>
    <Box as="li">
      <Link href="/settings/members">Members</Link>
    </Box>
    <Box as="li">
      <Link href="/settings/billing">Billing</Link>
    </Box>
  </Stack>
</Box>

Within text

Put a Link inside Text when a sentence includes one destination. Make the linked words identify where the reader will go.

Read the deployment guide before publishing.

import { Link, Text } from "@smoothie-framework/whisk-react";

<Text>
  Read the <Link href="/guides/deployments">deployment guide</Link> before publishing.
</Text>

External

Set target when the product intentionally opens a new window. Add external to retain the supplied rel values and append noopener and noreferrer.

import { Link } from "@smoothie-framework/whisk-react";

<Link
  href="https://developer.mozilla.org/"
  target="_blank"
  external
>
  Open MDN documentation in a new tab <span aria-hidden="true">↗</span>
</Link>

Download

Use the native download attribute for a same-origin resource when downloading is the destination. Include the file type or result in the link text.

import { Link } from "@smoothie-framework/whisk-react";

<Link href="/reports/release-notes.pdf" download="release-notes.pdf">
  Download release notes (PDF)
</Link>

Router

Use asChild with a Next.js or React Router Link that renders an anchor and forwards anchor props. Whisk Link supplies styling and focus; the router link supplies the destination.

import NextLink from "next/link";
import { Link as RouterLink } from "react-router-dom";
import { Link } from "@smoothie-framework/whisk-react";

<Link asChild>
  <RouterLink to="/settings">Open workspace settings</RouterLink>
</Link>

<Link asChild>
  <NextLink href="/settings">Open workspace settings</NextLink>
</Link>

Props

Component props

PropTypeDefaultDescription
hrefstringnoneProvide the navigation destination for a direct Link. Omit it with asChild, where the router link owns the destination.
childrenReactNodenoneWrite text that identifies the destination or result of following the link.
size2xs | xs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl | 6xl | 7xl | 8xl | 9xlmdAdjust the link's shared type scale without changing its anchor semantics.
variantprimary | secondary | ghostprimaryChoose the link color style.
underlinealways | hover | nonealwaysControl the visual underline. Keep another non-color cue when removing it.
externalbooleanfalseAppend noopener and noreferrer to rel. It does not choose a target or validate the destination.
target | rel | download | aria-currentnative anchor attributesnoneUse native browser behavior for new windows, relationship hints, downloads, and current-page state.

Shared props

PropSupportedNotes
as / asChildYesChoose the rendered anchor host with as, or merge the component props into one child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered anchor host.
refYesForwards to the rendered anchor host.
Native HTML attributesYesNative attributes are forwarded to the rendered anchor host.

Accessibility

Link renders an anchor and includes a visible focus indicator. Use text that describes the destination or result, not Click here or a bare URL. Use Button for in-place actions. Mark the current navigation destination with aria-current="page". If a link opens a new window or downloads a file, make that outcome clear in its visible text or accessible name. external adds rel protection but does not open a new window. Do not remove the underline without preserving a clear non-color affordance.