# Link (w-link)

## Description

Link component to use when creating links that look like buttons.

[Warp component reference](https://warp-ds.github.io/docs/components/link/frameworks/elements)

## Usage

**Do:**

- Use the `<w-link>` component when you need a link that looks like a button.

**Do Not:**

- Use the `<w-link>` component when you need a link that looks like a link. In that case, use the native `<a>` tag.
- Use the `<w-link>` component when you need a button that looks like a button. In that case, use the native `<w-button>` tag.

The following table illustrates use cases and which element to use for the purpose.

| If desired behaviour is | and desired styling is | then use     |
| ----------------------- | ---------------------- | ------------ |
| link                    | button                 | `<w-link>`   |
| button                  | button                 | `<w-button>` |
| link                    | link                   | `<a>`        |
| button                  | link                   | `<w-button>` |

## Accessibility

## Examples

### Primary

<elements-example>

```html
<w-link variant="primary" href="#">Go to the top of this page</w-link>
```

</elements-example>

### Secondary

This is the default appearance.

<elements-example>

```html
<w-link href="#">Go to the top of this page</w-link>
```

</elements-example>

### Negative

<elements-example>

```html
<w-link variant="negative" href="#">Go to the top of this page</w-link>
```

</elements-example>

### Utility

<elements-example>

```html
<w-link variant="utility" href="#">Go to the top of this page</w-link>
```

</elements-example>

### Quiet

<elements-example>

```html
<w-link variant="quiet" href="#">Go to the top of this page</w-link>
```

</elements-example>

### Small

All variants can be small.

<elements-example>

```html
<w-link href="#" small>Go to the top of this page</w-link>
```

</elements-example>

### Full width


<elements-example>

```html
<w-link href="#" full-width>Go to the top of this page</w-link>
```

</elements-example>

## Styling API

## `<w-link>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| autofocus | `boolean` | `false` | Focus the link after it is rendered |
| disabled | `boolean` | `false` | Applies disabled styling, but you need to disable clicks on your own. |
| full-width | `boolean` | `false` | Makes the link take up the full width of its parent |
| href | `string \| undefined` | `-` | The URL the link points to |
| rel | `string \| undefined` | `-` | Relationship of the linked URL. |
| small | `boolean` | `false` | Render a smaller version |
| target | `string \| undefined` | `-` | Where to display the linked URL (e.g. `_blank`) |
| variant | [`ButtonVariant \| undefined`](#buttonvariant-undefined) | `-` | Visual style for the link/button. |

### Property Details

#### autofocus

Focus the link after it is rendered

- Type: `boolean`
- Default: `false`

#### disabled

Applies disabled styling, but you need to disable clicks on your own.

The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.

- Type: `boolean`
- Default: `false`

#### full-width

Makes the link take up the full width of its parent

- Type: `boolean`
- Default: `false`

#### href

The URL the link points to

- Type: `string | undefined`
- Default: `-`

#### rel

Relationship of the linked URL.

If `target="_blank"` and `rel` is not provided, the component uses `noopener`.

- Type: `string | undefined`
- Default: `-`

#### small

Render a smaller version

- Type: `boolean`
- Default: `false`

#### target

Where to display the linked URL (e.g. `_blank`)

- Type: `string | undefined`
- Default: `-`

#### variant

Visual style for the link/button.

- Type: [`ButtonVariant | undefined`](#buttonvariant-undefined)
- Default: `-`

### Types

#### ButtonVariant | undefined

`'negative' | 'primary' | 'secondary' | 'negativeQuiet' | 'utility' | 'quiet' | 'utilityQuiet' | 'overlay' | 'overlayInverted' | 'overlayQuiet' | 'overlayInvertedQuiet' | undefined`