Components / Controls

Link

An inline text link that takes the user somewhere. For an action that doesn't navigate, use Button.

Source Edit this page

Tones are readable

When to use

Links inside sentences, help text and footers.
external for pages outside your product.

Use something else when:

it performs an action (save, delete): Button
it is a whole clickable panel: Card with href

Usage

tsx

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

<Link href="/docs">Read the docs</Link>
<Link href="https://example.com" external>Example</Link>
<Link href="mailto:hello@example.com" tone="neutral" size="sm">Email us</Link>

External links

external opens a new tab with a safe rel, adds an external icon and announces "(opens in new tab)" to screen readers. Change that text with labels.external.

Tone and size

tone defaults to accent; text uses each tone's readable text colour. size defaults to inherit, so the link matches the surrounding text; sm, md and lg set a fixed size.

Props

Every prop of Link
Prop	What it does	Type	Default
`href`Required	Where the link goes.	`string`
`children`Required	The link text.	`ReactNode`
`tone`	Colour of the text. Default "accent".	`Tone`	`"accent"`
`size`	Text size; `inherit` follows the surrounding text. Default "inherit".	`Size \| "inherit"`	`"inherit"`
`external`	Opens in a new tab with a safe rel, an external icon and announced text.	`boolean`
`underline`	When the underline shows: `always` (default), `hover` (on hover and focus) or `none`. Leave it on in running text, where the underline is what tells a link from the words around it; take it off only where the place says it is a link (a navigation bar, a footer's columns, a card title).	`"none" \| "always" \| "hover"`
`aria-current`	Marks the link as the current item of a set, e.g. `"page"` for the page being shown in a navigation bar.	`boolean \| "false" \| "true" \| "page" \| "step" \| "location" \| "date" \| "time"`
`onClick`	Called when the link is activated.	`MouseEventHandler<HTMLAnchorElement>`
`labels`	Replace the built-in English text: `external` is read out after a link that opens in a new tab.	`{ external?: string; }`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only.	`CSSProperties`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
Click, `EnterEnter`	Follows the link, or calls `onClick`
`TabTab`	Focus with a visible ring

Safe schemes: href may be relative, http(s), mailto or tel. Other schemes are not linked.
Ref: the ref points at the anchor.

Theming

Tokens: --cy-link-underline-offset and --cy-link-underline-thickness.

createTheme({ components: { link: { underlineThickness: "2px" } } });

Button · Card

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

External linksLink to "External links"

Tone and sizeLink to "Tone and size"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"

RelatedLink to "Related"