# dds-link



<!-- Auto Generated Below -->


## Overview

A navigational element that takes users to another page or resource, most often placed within or directly following a sentence.

## Usage

### Link

Put the link text in the default slot and the destination in `href`.

```html
<dds-link href="https://dentsu.com">Visit dentsu.com</dds-link>
```

#### Within a sentence

`dds-link` is inline, so it sits in running text. It sets its own colour, size and weight rather than inheriting them from the surrounding text.

```html
<p>
  If you need help, read the
  <dds-link href="/resources">resources</dds-link> first.
</p>
```

#### Icons

Set `icon-start` or `icon-end` to a `dds-icon` name to reinforce meaning or direction. The icon is decorative; the label is the accessible name.

```html
<dds-link href="/previous" icon-start="chevron-left">Previous step</dds-link>
<dds-link href="/next" icon-end="chevron-right">Next step</dds-link>
```

#### Variants and sizes

`variant="subtle"` hides the underline until hover, which suits a link beside heavy type. `variant="ai"` uses the AI colour, which has a light-mode value only today. `size="s"` reduces the text and gap.

```html
<dds-link href="/welcome" variant="subtle" icon-end="arrow-right"
  >Welcome</dds-link
>
<dds-link href="/notes" size="s">Release notes</dds-link>
```

#### External links

`external` opens the link in a new tab with `rel="noopener noreferrer"` and appends an external-link icon. The component adds no text, so a screen reader is not told the link opens a new tab. Say so in the label or with `aria-label` if it matters.

```html
<dds-link href="https://dentsu.com" external>External resources</dds-link>
```

#### Disabled

`disabled` makes the link inert: it drops `href`, leaves the tab order and cannot be activated. The platform has no disabled state for a link, and `aria-disabled` is not used, so assistive technology does not announce it as disabled. Use it where a surrounding component, such as a navigation, needs a link that is temporarily unavailable.

```html
<dds-link href="https://dentsu.com" disabled>Unavailable</dds-link>
```

#### Naming

An icon-only link has no name. Give it one with `aria-label` on `dds-link`, which is forwarded to the inner anchor.

```html
<dds-link
  href="/next"
  icon-end="chevron-right"
  aria-label="Next step"
></dds-link>
```



## Properties

| Property    | Attribute    | Description                                                        | Type                            | Default     |
| ----------- | ------------ | ------------------------------------------------------------------ | ------------------------------- | ----------- |
| `disabled`  | `disabled`   | Renders the link inert: it is not focusable and does not navigate. | `boolean`                       | `false`     |
| `external`  | `external`   | Opens the link in a new tab and appends an external link icon.     | `boolean`                       | `false`     |
| `href`      | `href`       | The URL to link to. Ignored while `disabled`.                      | `string \| undefined`           | `undefined` |
| `iconEnd`   | `icon-end`   | Name of the icon to display after the link label.                  | `string \| undefined`           | `undefined` |
| `iconStart` | `icon-start` | Name of the icon to display before the link label.                 | `string \| undefined`           | `undefined` |
| `size`      | `size`       | Controls the visual size of the link.                              | `"m" \| "s"`                    | `"m"`       |
| `variant`   | `variant`    | Controls the visual style of the link.                             | `"ai" \| "default" \| "subtle"` | `"default"` |


## Slots

| Slot        | Description              |
| ----------- | ------------------------ |
|             | The default slot         |
| `"default"` | Slot for the link label. |


## Shadow Parts

| Part     | Description               |
| -------- | ------------------------- |
| `"root"` | The inner anchor element. |


## Dependencies

### Depends on

- [dds-icon](../icon)

### Graph
```mermaid
graph TD;
  dds-link --> dds-icon
  style dds-link fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*