# Link

A text link, an enhanced native `<a>`.

## Types

<DemoBlock title="Link types">
  <oas-link href="#">Default link</oas-link>
  <oas-link href="#" type="primary">Primary link</oas-link>
  <oas-link href="#" type="success">Success link</oas-link>
  <oas-link href="#" type="warning">Warning link</oas-link>
  <oas-link href="#" type="danger">Danger link</oas-link>
  <oas-link href="#" type="info">Info link</oas-link>
</DemoBlock>

## Color

The `color` attribute accepts 11 preset names (auto-adapting to light/dark themes) or any CSS color value (takes effect immediately, overriding the `type` semantic color). Custom color values are rendered as-is — make sure the text contrast meets WCAG AA (4.5:1).

<DemoBlock title="Preset palette">
  <oas-link href="#" color="magenta">magenta</oas-link>
  <oas-link href="#" color="red">red</oas-link>
  <oas-link href="#" color="volcano">volcano</oas-link>
  <oas-link href="#" color="orange">orange</oas-link>
  <oas-link href="#" color="gold">gold</oas-link>
  <oas-link href="#" color="lime">lime</oas-link>
  <oas-link href="#" color="green">green</oas-link>
  <oas-link href="#" color="cyan">cyan</oas-link>
  <oas-link href="#" color="blue">blue</oas-link>
  <oas-link href="#" color="geekblue">geekblue</oas-link>
  <oas-link href="#" color="purple">purple</oas-link>
</DemoBlock>

<DemoBlock title="Custom color values (override type)">
  <!-- Custom colors use theme tokens (var() is a valid CSS color, injected as-is): a fixed hex
       cannot meet contrast in both themes, while semantic tokens ship compliant variants per theme -->
  <oas-link href="#" color="var(--oas-color-info-text)">Teal link</oas-link>
  <oas-link href="#" type="primary" color="var(--oas-preset-purple-text)">Purple overriding primary</oas-link>
</DemoBlock>

## Underline

`underline` three modes: `hover` (default, appears on hover) / `always` (persistent) / `never` (none). Compat shorthands: bare `underline` or `underline="true"` = always, `underline="false"` = never.

Underline offset and color are customizable via CSS variables: `--oas-link-underline-offset` (default 2px), `--oas-link-underline-color` (default follows text color).

<DemoBlock title="Underline modes">
  <oas-link href="#">hover (default, on hover)</oas-link>
  <oas-link href="#" underline="always">always</oas-link>
  <oas-link href="#" underline="never">never</oas-link>
  <oas-link href="#" underline="always" style="--oas-link-underline-offset: 4px; --oas-link-underline-color: var(--oas-color-danger);">offset 4px + red underline</oas-link>
</DemoBlock>

## Icon

The `icon` attribute adds an icon (name from the registry); `icon-position="start|end"` controls placement:

<DemoBlock title="Links with icons">
  <oas-link href="#" icon="search">Search docs</oas-link>
  <oas-link href="#" icon="arrow-right" icon-position="end">View details</oas-link>
</DemoBlock>

## External

`external` auto-adds `target="_blank"` + `rel="noopener noreferrer"` + an external-link icon:

<DemoBlock title="External link">
  <oas-link href="https://example.com" external>External docs</oas-link>
</DemoBlock>

## Disabled & new window

<DemoBlock title="Disabled & target">
  <oas-link href="#" disabled>Disabled link</oas-link>
  <oas-link href="https://example.com" target="_blank" type="primary">Open in new window</oas-link>
</DemoBlock>

## Font size

The `size` attribute has three tiers: `small` (auxiliary small text) / `medium` (default) / `large` (title-like large text). Font sizes go through the `--oas-font-size-*` tokens.

<DemoBlock title="Font size tiers">
  <oas-link href="#" size="small">Auxiliary small link</oas-link>
  <oas-link href="#">medium (default)</oas-link>
  <oas-link href="#" size="large">Title-like large link</oas-link>
</DemoBlock>

## Download

`download` is passed through to the native `<a download>`: with a bare `download` the browser uses the original filename, with a value it sets a custom filename (when combined with `target="_blank"` browsers ignore `download`).

<DemoBlock title="Download links">
  <oas-link href="/files/oas-ui-guide.pdf" download>Download guide (original filename)</oas-link>
  <oas-link href="/files/oas-ui-guide.pdf" download="oas-guide.pdf" icon="download" icon-position="end">Download guide (custom filename)</oas-link>
</DemoBlock>

## Loading

`loading` enters the loading state: the leading icon is replaced by a spinner (one is added automatically when there is no icon) and clicks are blocked (no `oas-click` is dispatched, no navigation) — suited for click-then-async navigation/submit flows; `aria-busy` is kept in sync.

<DemoBlock title="Loading">
  <oas-link href="#" loading>Loading (spinner added automatically)</oas-link>
  <oas-link href="#" icon="search" loading>Searching (leading icon replaced)</oas-link>
</DemoBlock>

## Events

<DemoBlock title="Click event">
  <oas-link href="#" type="primary" onoas-click="message.info('oas-click event fired')">Click link</oas-link>
</DemoBlock>

Clicking dispatches the `oas-click` CustomEvent; `detail.originalEvent` is the native MouseEvent.

## API

### oas-link

#### Attributes

| Attribute | Description | Type | Default |
| --- | --- | --- | --- |
| `color` | Color: accepts 11 preset names (mapped to `--oas-preset-*-text` compliant tokens) or any CSS color value, overriding the `type` semantic color | `string` | — |
| `disabled` | Disabled | `boolean` | — |
| `download` | Passthrough `download` attribute (native `<a download>` file download) | `string` | — |
| `external` | External link: automatically adds `target="_blank"`, `rel="noopener noreferrer"`, and an external-link icon | `boolean` | — |
| `href` | Link URL | `string` | — |
| `icon` | Icon name (from the oas-icon set), placed before or after the text (see `icon-position`) | `string` | — |
| `icon-position` | Icon position: `start` (default, before the text) / `end` (after the text); defaults to `end` for the `external` icon only | — | — |
| `loading` | Loading state: spinner replaces the leading icon and blocks clicks (async navigation/submit on click) | `boolean` | — |
| `size` | Font size step: `small`/`medium` (default)/`large` | `string` | — |
| `target` | Open behavior | `string` | — |
| `type` | Type | `LinkType` | `default` |
| `underline` | Underline | `string` | — |

#### Events

| Event | Description |
| --- | --- |
| `oas-click` | Click, `detail: { originalEvent }` |

#### Slots

| Name | Description |
| --- | --- |
| default | Link content (text / icons) |

#### CSS Variables

| CSS Variable | Default |
| --- | --- |
| `--oas-link-color` | `var(--oas-color-text-primary)` |
| `--oas-link-underline-color` | `currentColor` |
| `--oas-link-underline-offset` | `2px` |