Skip to content

Link

Anchor primitive with token-driven styling, underline behaviour, and safe defaults for external destinations.

stable
since v0.1.0
3.88 kB
typography
navigation

Preview

tsx

import { Link } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Link href="/docs">Read the documentation</Link>;
}

Variants

Three visual variants tune emphasis without changing semantics: default, subtle (for muted body links), and emphasis (for hero or callout links).

Preview

tsx

import { Link } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1rem' }}>
      <Link href="/docs" variant="default">
        Default link
      </Link>
      <Link href="/docs" variant="subtle">
        Subtle link
      </Link>
      <Link href="/docs" variant="emphasis">
        Emphasised link
      </Link>
    </div>
  );
}

Underline

underline controls underline behaviour — hover (default), always, or none. Pick the option that matches how prominent the link should look in flow.

Preview

tsx

import { Link } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1rem' }}>
      <Link href="/docs" underline="hover">
        Underline on hover
      </Link>
      <Link href="/docs" underline="always">
        Always underlined
      </Link>
      <Link href="/docs" underline="none">
        No underline
      </Link>
    </div>
  );
}

External

Pass external to automatically set target="_blank", append rel="noopener noreferrer", and render a decorative indicator icon. Caller-provided rel and target merge cleanly with the safe defaults.

Preview

tsx

import { Link } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Link href="https://github.com/arshad-shah/cynosure" external>
      View Cynosure on GitHub
    </Link>
  );
}

Inline usage

Drop a Link inside a Text to keep paragraph flow while remaining keyboard accessible.

Preview

tsx

import { Link, Text } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Text>
      Read the <Link href="/docs">getting started guide</Link> to pick up the basics, then explore
      the <Link href="/components">component catalogue</Link>.
    </Text>
  );
}

Disabled

disabled cancels navigation, sets aria-disabled, and applies the muted style — use sparingly since disabled links are easy to miss.

Preview

tsx

import { Link } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Link href="/docs" disabled>
      Unavailable link
    </Link>
  );
}

API

PropTypeDefaultDescription

variant

"default"|"subtle"|"emphasis"

"default"

Visual emphasis: `default` for primary links, `subtle` for tertiary navigation, `emphasis` for headline / hero CTAs.

underline

"always"|"hover"|"none"

"hover"

When the underline is drawn — `always`, only on `hover`, or `none`.

external

boolean

—

Marks the link as external: forces `rel="noopener noreferrer"`, `target="_blank"`, and appends a decorative arrow icon. The icon is `aria-hidden` so screen readers aren't double-announced.

disabled

boolean

—

Visually mutes the link and blocks `onClick`. Adds `aria-disabled`.

className

string

—

Additional class names appended after Cynosure's base classes.

style

CSSProperties

—

Inline style overrides merged last.

children

ReactNode

—

Link content.

padding

Responsive<SpaceToken>

—

Padding on all four sides. Token from the spacing scale.

paddingX

Responsive<SpaceToken>

—

Horizontal padding (left + right). Overrides `padding` on the X axis.

paddingY

Responsive<SpaceToken>

—

Vertical padding (top + bottom). Overrides `padding` on the Y axis.

paddingTop

Responsive<SpaceToken>

—

Padding on the top edge. Beats `padding` / `paddingY`.

paddingRight

Responsive<SpaceToken>

—

Padding on the right (inline-end in RTL) edge.

paddingBottom

Responsive<SpaceToken>

—

Padding on the bottom edge.

paddingLeft

Responsive<SpaceToken>

—

Padding on the left (inline-start in RTL) edge.

margin

Responsive<MarginValue>

—

Margin on all four sides. Accepts the spacing scale or `"auto"`.

marginX

Responsive<MarginValue>

—

Horizontal margin (left + right). Use `"auto"` to centre.

marginY

Responsive<MarginValue>

—

Vertical margin (top + bottom).

marginTop

Responsive<MarginValue>

—

Margin on the top edge.

marginRight

Responsive<MarginValue>

—

Margin on the right edge.

marginBottom

Responsive<MarginValue>

—

Margin on the bottom edge.

marginLeft

Responsive<MarginValue>

—

Margin on the left edge.

width

Responsive<SizeValue>

—

Element width. Accepts a `SpaceToken`, `LengthValue`, or named alias.

height

Responsive<SizeValue>

—

Element height. Accepts a `SpaceToken`, `LengthValue`, or named alias.

minWidth

Responsive<SizeValue>

—

Minimum width — useful for preventing flex children from collapsing.

maxWidth

Responsive<SizeValue>

—

Maximum width — `"prose"` caps to a comfortable reading measure.

minHeight

Responsive<SizeValue>

—

Minimum height.

maxHeight

Responsive<SizeValue>

—

Maximum height.

background

Responsive<ColorToken>

—

Background colour. Use a `ColorToken` like `"bg.surface"` for theme awareness.

color

Responsive<ColorToken>

—

Text colour. Inherits unless set.

borderColor

Responsive<ColorToken>

—

Border colour. Pair with `borderWidth` to make the border visible.

borderWidth

Responsive<BorderWidth>

—

Border thickness in scale steps.

borderStyle

Responsive<BorderStyle>

—

Border line style.

borderRadius

Responsive<RadiusToken>

—

Corner rounding token.

boxShadow

Responsive<ShadowToken>

—

Drop-shadow token from the elevation scale.

opacity

Responsive<number | `${number}`>

—

Opacity 0–1. Use sparingly — prefer surface tokens over translucency.

overflow

Responsive<Overflow>

—

How content that exceeds the box is handled.

overflowX

Responsive<Overflow>

—

Horizontal-axis overflow control. Overrides `overflow` for the X axis.

overflowY

Responsive<Overflow>

—

Vertical-axis overflow control.

display

Responsive<Display>

—

CSS `display` value. `"contents"` removes the element's box from layout.

position

Responsive<Position>

—

CSS `position`. Pair with `top`/`right`/`bottom`/`left` for placement.

top

Responsive<InsetValue>

—

Top inset (when positioned). Accepts a `SpaceToken`, `"auto"`, `"0"`, or `LengthValue`.

right

Responsive<InsetValue>

—

Right inset (when positioned).

bottom

Responsive<InsetValue>

—

Bottom inset (when positioned).

left

Responsive<InsetValue>

—

Left inset (when positioned).

zIndex

Responsive<ZIndexToken>

—

Stacking-context layer token (`"modal"`, `"tooltip"`, …).

gridColumn

Responsive<string>

—

Grid-column shorthand (e.g. `"1 / 3"`, `"span 2"`).

gridRow

Responsive<string>

—

Grid-row shorthand.

gridArea

Responsive<string>

—

Named grid area.

flex

Responsive<"none" | "1" | "auto" | "initial" | (string & {})>

—

Shorthand: `1 | auto | none | initial | <css>`. Resolves to `flex` on the child.

flexGrow

Responsive<number | `${number}`>

—

Grow factor inside a flex container.

flexShrink

Responsive<number | `${number}`>

—

Shrink factor inside a flex container.

flexBasis

Responsive<"content" | SizeValue>

—

Initial main-axis size before grow/shrink.

alignSelf

Responsive<AlignSelf>

—

Override `align-items` for a single child.

justifySelf

Responsive<JustifySelf>

—

Override `justify-items` for a single child (grid).

order

Responsive<number | `${number}`>

—

Flex/grid child reorder index.

asChild

boolean

—

When `true`, renders the primitive's single React child via `Slot`, forwarding className/style/ref/event handlers onto it.

Accessibility

Always write link text that stands on its own — avoid bare “click here” or “read more” copy.
external adds rel="noopener noreferrer" automatically so target="_blank" never leaks window.opener.
The external indicator icon is aria-hidden; the link text alone carries meaning for screen readers.
disabled sets aria-disabled="true" and blocks the click handler, but the anchor remains in the tab order — prefer hiding or replacing the link when it has no destination.
Underline + colour together carry the link signal so colour-blind users aren’t dependent on hue alone.

Recipes

Use underline="always" for body links that must stand out against long-form prose.
Drop Link asChild over a framework router link to inherit Cynosure styling without losing client-side navigation: <Link asChild><NextLink href="/next">Next</NextLink></Link>.
Combine variant="subtle" with breadcrumbs or footer rows where many links sit close together.
Pair external with descriptive copy (“View on GitHub”) so the destination is obvious before the click.