# Link

> A styled anchor, with the security attributes an external link needs.

A link is an anchor with the library’s underline treatment and palette. It is exported under two names — `link` and `textLink` — because `link` is also javascript-to-html’s `<link>` element, and importing both under one name is a syntax error. Use `textLink`, or import the library as a namespace.

## Basic link

```javascript
text('Read the ', link({ href: '/docs' }, 'documentation'), ' to get started.')
```

## Colors

```javascript
stack({ direction: 'row', gap: 'lg', wrap: true },
  link({ href: '#', color: 'primary' }, 'Primary'),
  link({ href: '#', color: 'neutral' }, 'Neutral'),
  link({ href: '#', color: 'success' }, 'Success'),
  link({ href: '#', color: 'warning' }, 'Warning'),
  link({ href: '#', color: 'danger' }, 'Danger'),
)
```

## Subtle

A subtle link inherits the surrounding colour and shows its underline on hover — for lists of links where an underline on every row would be noise.

```javascript
stack({ gap: 'xs' },
  link({ href: '/docs/routing', subtle: true }, 'Routing'),
  link({ href: '/docs/data', subtle: true }, 'Data loading'),
  link({ href: '/docs/assets', subtle: true }, 'Assets and styling'),
)
```

## External links

`external` adds `target="_blank"` and the `rel` that has to come with it. Say in the link text that it opens a new tab, or add a visually hidden note — a new tab with no warning is disorienting.

```javascript
text(
  'The library is on ',
  link({ href: 'https://www.npmjs.com/package/sitelo', external: true },
    'npm',
    visuallyHidden(' (opens in a new tab)'),
  ),
  '.',
)
```

## In a paragraph

```javascript
text({ variant: 'lead' },
  'sitelo is built on ',
  link({ href: 'https://vite.dev', external: true }, 'Vite'),
  ', renders with ',
  link({ href: 'https://ht.js.org', external: true }, 'javascript-to-html'),
  ', and ships nothing to the browser unless you ask it to.',
)
```

## When to use a button instead

A link navigates; a button performs an action. If the thing changes state on the page rather than taking the reader somewhere, it should be a `button()` — and if it navigates but should look like a button, give `button()` an `href`, which renders an anchor underneath.

```javascript
stack({ direction: 'row', gap: 'md', align: 'center', wrap: true },
  link({ href: '/docs' }, 'A link that navigates'),
  button({ href: '/docs', variant: 'outline' }, 'A link that looks like a button'),
  button({ variant: 'link' }, 'A button that looks like a link'),
)
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | Where it goes. |
| `color` | `'primary' \| 'neutral' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | Which palette to draw from. |
| `subtle` | `boolean` | `false` | Inherit the surrounding colour; underline on hover only. |
| `external` | `boolean` | `false` | Adds target="_blank" and rel="noopener noreferrer". |